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PREFACE 



This manual Is about the ATARI Personal Computer System. It covers both 
the ATARI 400™ and the ATARI 800 w computers. These two computers are 
electrically identical, differing only in mechanical features such as the 
keyboards and cartridge slots. The purpose of this manual is to explain in 
detail how to use all the features of the ATARI Personal Computer System. 
This Is a complex and powerful machine, and the explanations are accordingly 
rather long. Furthermore, they demand some expertise on the part of the 
reader. This book Is not Intended for the beginning programmer. The reader 
should be thoroughly familiar with the BASIC Reference Manual provided with 
the computer. Familiarity with assembly language Is also essential. A 
glossary In the back defines and explains some of the less commonly 
encountered jargon. However, this glossary does not Include terms that every 
serious personal computer programmer should already know. 

This book was written as a training manual for professional programmers 
wishing to use the ATARI Personal Computer System. At some later date It may 
be modified for general use. It does not supplant the technical reference 
manual (ATARI part number C016555). That manual ts a reference manual; It is 
very useful for programmers who already understand the system. This book is 
Intended to be a tutorial; it will explain ideas and possibilities rather 
than define registers and control codes. 

The Software Development Support Group wrote this book. Chris Crawford 
wrote chapters 1 through 6 and Appendices I and II. Lane Winner wrote 
chapter 7 and Appendix IV with assistance from Jim Cox. Amy Chen wrote 
Appendix III. Mike Ekberg wrote chapters 8 and 9 with assistance from John 
Eckstrom. Kathleen Pitta wrote Appendix X. Bob Fraser wrote Chapter 10. 
Gus Makreas prepared the glossary and table of contents. The final result 
has many flaws, but we are proud of It. 





CHAPTER 1 
SYSTEM OVERVIEW 



The ATARI Personal Computer System Is a second generation personal 
computer. First and foremost, It Is a consumer computer. The thrust of the 
design Is to make the consumer comfortable with the computer. This consumer 
orientation manifests Itself In many ways. First, the machine Is 
Idiot-proofed; the consumer Is protected from mistakes by such things as 
polarized connectors that will not go In the wrong way, a power Interlock on 
the lid to the internal electronics, and a pair of plastic shields protecting 
the SYSTEM RESET key. Second, the machine has a great deal of graphics 
power; people respond to pictures much more readily than to text. Third, the 
machine has strong sound capabilities; again, people respond to direct 
sensory Input better than to Indirect textual messages. Finally, the 
computer has joysticks and paddles for more direct tactile Input than Is 
possible with keyboards. The point here is not that the computer has lots of 
features but rather that the features are all part of a consistent design 
philosophy aimed directly at the consumer. The designer who does not 
appreciate this fundamental fact will find himself working against the grain 
of the system. 

The Internal layout of the ATARI 400/800 1 " computer Is very different 
from other systems. It of course has a microprocessor (a 6502), RAM, ROM, 
and a PI A. However, It also has three special purpose LSI chips known as 
ANTIC, POKEY, and CTIA. These chips were designed by Atari engineers 
primarily to take much of the burden of housekeeping off of the 6502, thereby 
freeing the 6502 to concentrate on computations. While they were at It, they 
designed a great deal of power into these chips. Each of these chips is 
almost as big (In terms of silicon area) as a 6502, so the three of them 
together provide a tremendous amount of power. Mastering the ATARI 400/800 
Is primarily a matter of mastering these three chips. 

ANTIC is a microprocessor dedicated to the television display. It Is a 
true microprocessor; It has an Instruction set, a program (called the display 
list), and data. The display list and the display data are written into RAM 
by the 6502. ANTIC retrieves this Information from RAM using DMA. It 
processes the higher level Instructions In the display list and translates 
these Instructions Into a real -time stream of simple Instructions to CTIA. 

CTIA Is a television Interface chip. ANTIC directly controls most of 
CTIA f s operations, but the 6502 can be programmed to intercede and control 
some or all of CTIA's functions. CTIA converts the digital commands from 
ANTIC (or the 6502) Into the signal that goes to the television. CTIA also 
adds some factors of Its own, such as color values, p I ayer-ml ss 1 1 e graphics, 
and collision detection. 

POKEY Is a digital I/O chip. It handles such disparate tasks as the 
serial I/O bus, audio generation, keyboard scan, and random number 
generation. It also digitizes the resistive paddle Inputs and controls 
maskable Interrupt (IRQ) requests from peripherals. 

All four of these LSI chips function simultaneously. Careful separation 
of their functions In the design phase has minimized conflicts between the 
chips. The only hardware level conflict between any two chips In the system 
occurs when ANTIC needs to use the address and data busses to fetch Its 
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display Information. To do this, It halts the 6502 and takes control of the 
busses. 

As with all 6502 systems, the I/O Is memory-mapped. Figure 1.1 presents 
the coarse memory map for the computer. Figure 1.2 shows the hardware 
arrangement. 
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Figure 1.1 
Coarse Memory Map for ATARI 400/800 
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CHAPTER 2 
ANTIC AND THE DISPLAY LIST 



TELEVISION DISPLAYS 

In order to understand the graphics capabilities of the ATARI Personal 
Computer System one must first understand the rudiments of how a television 
set works. Television sets use what Is called a raster scan display system. 
An electron beam Is generated at the rear of the television tube and shot 
toward the television screen. Along the way, It passes between sets of 
horizontal and vertical colls which, if energized, can deflect the beam. In 
this way the beam can be made to strike any point on the screen. The 
electronics Inside the television set cause the beam to sweep across the 
television screen in a regular fashion. The beam f s intensity can also be 
controlled. If you make the beam more Intense the spot In the screen that It 
strikes will glow brightly; If you make It less intense the spot will glow 
dimly or not at all. 

The beam starts at the top left corner of the screen and traces 
horizontally across the screen. As it sweeps across the screen, Its 
intensity changes will paint an Image on the screen. When it reaches the 
right edge of the screen, It is turned off and brought back to left side of 
the screen. At the same time It Is moved down just a notch. It then turns 
back on and sweeps across the screen again. This process Is repeated for a 
total of 262 sweeps across the screen. (There are actually 525 sweeps across 
the screen In an alternating system known as Interlace. We will Ignore 
interlace and act as if the television has only 262 lines.) These 262 lines 
fill the screen from top to bottom. At the bottom of the screen (after the 
262nd line Is drawn), the electron beam is turned off and returned to the 
upper left corner of the screen. Then It starts the cycle all over again. 
This entire cycle happens 60 times every second. 

Now for some jargon: a single trace of the beam across the screen is 
called a horizontal scan line 1 . A horizontal scan line is the fundamental 
unit of meausurement of vertical distance on the screen. You state the 
height of an Image by specifying the number of horizontal scan lines It 
spans. The period during which the beam returns from the right edge to the 
left edge is called the 'horizontal blank 1 . The period during which the beam 
returns to the top of the screen is called the 'vertical blank*. The entire 
process of drawing a screen takes 16,684 microseconds. The vertical blank 
period Is about 1400 microseconds. The horizontal blank takes 14 
microseconds. A single horizontal line takes 64 microseconds. 

Most television sets are designed with 'overscan 1 ; that means that they 
spread the Image out so that the edges of picture are off the edge of the 
television tube. This guarantees that you have no unsightly borders In your 
TV picture. It Is very bad for computers, though, because screen information 
that Is off the edge of the picture does you no For this reason the picture 
that the computer puts out must be somewhat smaller than what the television 
can theoretically display. For this reason only 192 horizontal scan lines 
are normally used by the Atari display. Thus, the normal limit of resolution 
of a television set used with this computer is 192 pixels vertically. The 
standard unit of horizontal distance Is the 'color clock'. You specify the 
width of an image by stating how many color clocks wide It Is. There are 228 
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color clocks in a single horizontal scan line, of which a maximum of 176 are 
actually visible. Thus, the ultimate limit for full color horizontal 
resolution with a standard color television Is 176 pixels. It Is possible 
with the ATARI Personal Computer System to go even finer and control 
Individual half-clocks. This gives a horizontal resolution of 352 pixels. 
However, use of this feature will produce Interesting color effects known as 
color artifacts. Color artifacts can be a nuisance If they are not desired; 
they can be a boon to the programmer who desires additional color and Is not 
fazed by their restrictions. 



COMPUTERS AND TELEVISIONS 

The fundamental problem any microcomputer has In using a raster scan 
television for display purposes is that the television display Is a dynamic 
process; because of this the television does not remember the Image. 
Consequently, the computer must remember the screen Image and constantly send 
a signal to the television telling It what to display. This process of 
sending Information to the television Is a continuous process and It requires 
full-time attention. For this reason most microcomputers have special 
hardware circuits that handle the television. The basic arrangement Is the 
same on virtually all systems: 

microprocessoi >screen RAM >vtdeo hardware >TV screen 

The microprocessor writes information to the screen RAM area that holds the 
screen data. The video hardware Is constantly dipping into this RAM area, 
getting screen data which It converts Into television signals. These signals 
go to the television which then displays the Information. The screen memory 
is mapped onto the screen In the same order that It follows In RAM. That is, 
the first byte In the screen memory maps to the top left corner of the 
screen, the second byte maps one position to the right, then the third, the 
fourth, and so on to the last byte which Is mapped to the lower right corner 
of the screen. 

The quality of the Image that gets to the screen depends on two factors: 
the quality of the video hardware, and the quantity of screen RAM used for 
the display. The simplest arrangement Is that used by TRS-80 and PET. 
(TRS-80 Is a trademark of Radio Shack Co; PET Is a trademark of Commodore 
Business Machines.) Both of these machines allocate a specific 1K of RAM as 
screen memory. The video hardware circuits simply pull data out of this 
area, Interpret It as characters (using a character set in ROM), and put the 
resulting characters onto the screen. Each byte represents one character, 
allowing a choice of 256 different characters In the character set. With 1K 
of screen RAM one thousand characters can be displayed on the screen. There 
Isn f t much that can be done with this arrangement. The Apple uses more 
advanced video hardware. (Apple Is a trademark of Apple Computers.) Three 
graphics modes are provided: text, lo-res graphics, and hi-res graphics. The 
text graphics mode operates In much the same way that the PET and TRS-80 
displays operate. In the low-resolution graphics mode, the video hardware 
reaches into screen memory and Interprets It differently. Instead of 
Interpreting each byte as a character, each byte Is Interpreted as a pair of 
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color nybbles. The value of each nybble specifies the color of a single 
pixel. In the h Igh-resol utlon graphics mode each bit In screen memory Is 
mapped to a single pixel. If the bit Is on, the pixel gets color In It; If 
the bit Is off, the pixel stays dark. The situation Is complicated by a 
variety of design nuances In the Apple, but that Is the basic idea. The 
Important Idea Is that the Apple has three display modes; three completely 
different ways of Interpreting the data In screen memory. The Apple video 
hardware Is smart enough to Interpret a screen memory byte as either an 8-bit 
character (text mode), two 4-bit color nybbles (lo-res mode), or 7 Individual 
bits for a bit map (ht-res mode). 



ANTIC, A VIDEO MICROPROCESSOR 

The ATARI 400/800™ display list system represents a generalization of 
these systems. Where PET and TRS-80 have one mode and Apple has three modes, 
the ATARI 400/800 w has 14 modes. The second Important difference Is that 
display modes can be mixed on the screen. That Is, the user Is not 
restricted to a choice between a screenful of text or a screenful of 
graphics. Any collection of the 14 graphics modes can be displayed on the 
screen. The third Important difference Is that the screen RAM can be located 
anywhere In the address space of the computer and moved around while the 
program Is running, while the other machines use fixed screen RAM areas. 

All of this generality Is made possible by a video microprocessor called 
ANTIC. Where the earlier systems used rather simple video circuitry, Atari 
designed a full-scale microprocessor just to handle the Intracacles of the 
television display. ANTIC Is a true microprocessor; It has an Instruction 
set, a program, and data. The program for ANTIC Is called the display list. 
The display list specifies three things: where the screen data may be found, 
what display modes to use to Interpret the screen data, and what special 
display options (If any) should be implemented. When using the display list, 
it Is Important to shed the old view of a screen as a homogeneous Image In a 
single mode and see It Instead as a stack of f mode lines 1 . A mode line Is a 
collection of horizontal scan lines. It streches horizontally all the way 
across the screen. A Graphics 2 mode line Is 16 horizontal scan lines high, 
while a Graphics 7 mode line Is only two scan lines high. Many Graphics 
modes available from BASIC are homogeneous; an entire screen of a single mode 
Is set up. One must not limit her imagination to this pattern; with the 
display list you can create any sequence of mode lines down the screen. The 
display list Is a collection of code bytes which specify that sequence. 

ANTIC'S Instruction set is rather simple. There are four classes of 
instructions: map mode Instructions, character mode Instructions, blank line 
Instructions, and Jump instructions. Map mode instructions cause ANTIC to 
display a mode line with simple colored pixels (no characters). Character 
mode instructions cause ANTIC to display a mode line with characters In It. 
Blank line Instructions cause ANTIC to display a number of horizontal scan 
lines with solid background color. Jump Instructions are analogous to a 6502 
JMP Instruction; they reload ANTIC 1 s program counter. There are also four 
special options that can sometimes be specified by setting a designated bit 
In the ANTIC Instruction. These options are: display list Interrupt (DLI), 
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load memory scan (LMS), vertical scroll, and horizontal scroll. 

Map mode instructions cause ANTIC to display a mode line containing 
pixels with solid color In them. The color displayed comes from a color 
register. The choice of color register is specified by the value of the 
screen data. In four-color map modes (BASIC modes 3, 5, and 7, and ANTIC 
modes 8, A, D, and E) , a pair of bits Is required to specify a color: 



value of bit pair 

00 0 

01 1 

10 2 

11 3 



color register used 
COLBAK 
COLPF0 
C0LPF1 
C0LPF2 



Since only two bits are needed to specify one pixel, 4 pixels are encoded In 
each screen data byte. For example, a byte of screen data containing the 
value $1B would display four pixels; the first would be the background, the 
second would be color register 0, the third would be color register 1, and 
the fourth would be color register 2: 

$1B = 00011011 = 00 01 10 11 

In two-color map modes (BASIC modes 4, 6, and 8, and ANTIC modes 9, B, C, and 
F) each bit specifies one of two color registers. A bit value of 0 selects 
background color for the pixel and a bit value of 1 selects color register 0 
for the pixel. Eight pixels can be stored In one screen data byte. 

There are eight different map display modes. They differ in the number 
of colors they display (2 vs 4), the vertical size one mode line occupies (1 
scan line, 2, 4, or 8), and the number of pixels that fit horizontally Into 
one mode line (40, 80, 160, or 320). Thus, some map modes give better 
resolution; these will of course require more screen RAM. Figure 2.1 
presents this Information for all modes: 
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ANTIC 


BASIC 


number 


scan II nes/ 


pixels/ 


bytes/ 


bytes/ 


mode 


mode 
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mode 1 1 ne 
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screen 
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none 


4 


16 


40 


40 


480 
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1 


5 


8 


20 


20 


480 


7 


2 


5 


16 


20 


20 


240 


8 


3 


4 


8 


40 


10 


240 


9 


4 


2 


4 


80 


10 


480 


A 


5 


4 


4 


80 


20 


960 


B 


6 


2 


2 


160 


20 


1920 


C 


none 


2 


1 


160 


20 


3840 


D 


7 


4 


2 


160 


40 


3840 


E 


none 


4 


1 


160 


40 


7680 


F 


8 


2 


1 


320 


40 


7680 



Figure 2.1 
ANTIC mode line requirements 



Character mode Instructions cause ANTIC to display a mode line with 
characters In It. Each byte In screen RAM specifies one character. There 
are six character display modes. Character displays are discussed In Chapter 
3. 

Blank line instructions produce blank lines with solid background color. 
There are eight blank line Instructions; they specify skipping one through 
eight blank I Ines. 

There are two jump instructions. The first (JMP) Is a direct jump; It 
reloads ANTIC's program counter with a new address which follows the JMP 
Instruction as an operand. Its only function ts to provide a solution to a 
tricky problem: ANTIC 1 s program counter has only ten bits of counter and six 
bits of latch and so the display lit cannot cross a 1K boundary. If the 
display list must cross a 1K boundary then It must use a JMP Instruction to 
hop over the boundary. Note that this means that display lists are not fully 
relocatable. 

The second jump instruction (JVB) Is more commonly used. It reloads the 
program counter with the value In the operand and waits for the television to 
perform a vertical blank. This Instruction Is normally used to terminate a 
display list by jumping back up to the top of the display list. Jumping up 
to the top of the display list turns It Into an Infinite loop; waiting for 
vertical blank Insures that the Infinite loop Is synchronized to the display 
cycle of the television. Both JMP and JVB are three byte Instructions; the 
first byte Is the opcode, the second and third bytes are the address to jump 
to ( lo then hi) . 
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The four special options mentioned previously will be discussed In 
Chapters 5 and 6. The load memory scan (LMS) option must have a preliminary 
explanation. This option is selected by setting bit 6 of a map mode or a 
character mode Instruction byte. When ANTIC encounters such an Instruction, 
It will load Its memory scan counter with the following two bytes. This 
memory scan counter tells ANTIC where the screen RAM Is. It will begin 
fetching display data from this area. The LMS Instruction Is a three byte 
Instruction: one byte opcode followed by two bytes of operand. In simple 
display lists the LMS Instruction Is used only once, at the beginning of the 
display list. It may sometimes be necessary to use a second LMS Instruction. 
The need arises when the screen RAM area crosses a 4K boundary. The memory 
scan counter has only 12 bits of counter and 4 bits of latch; thus, the 
display data cannot cross a 4K boundary. In this case an LMS Instruction 
must be used to jump the memory scan counter over the boundary. Note that 
this means that display data is not fully relocatable. LMS Instructions have 
wider uses which will be discussed later. 



BUILDING DISPLAY LISTS 

Every display list should start off with 3 »blank 8 lines 1 instructions. 
This Is to defeat vertical overscan by bringing the beginning of the display 
24 scan lines down. After this Is done the first display line should be 
specified. Simultaneously, the LMS should be used to tell ANTIC where It 
will find the screen RAM. Then follows the display list proper, which lists 
the display bytes for the mode lines on the screen. The total number of 
horizontal scan lines produced by the display list should always be 192 or 
less; ANTIC does not maintain the screen timing requirements of the 
television. If you give ANTIC too many scan lines to display It will do so, 
but the television screen will probably roll. Displaying fewer than 192 scan 
lines will cause no problems; indeed, it will decrease 6502 execution time by 
reducing the number of cycles stolen by ANTIC. The programmer must calculate 
the sum of the horizontal scan lines produced by her display list and verify 
It herself. The display list terminates with a JVB Instruction. Here Is a 
typical display list for a standard BASIC Graphics mode 0 display (all values 
are In hexadecimal): 
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70 blank 8 I Ines 
70 blank 8 I Ines 
70 blank 8 I Ines 

42 display ANTIC mode 2 (BASIC mode 0) 
20 also, screen memory starts at 7C20 
7C 

02 display ANTIC mode 2 

02 

02 

02 

02 

02 

02 

02 

02 

02 

02 

02 

02 

02 

02 

02 

02 

02 

02 

02 

02 

02 

02 

41 jump and wait for vertical blank 
E0 to display list which starts at 
7B $7BE0 



As you can see, this display list is short only 32 bytes. Most 

display lists are less than 100 bytes long. Furthermore, they are quite 
simple In structure and easy to set up. 

To Implement your own display list you must first design the display 
format. This Is best done on paper. Lay out the screen Image and translate 
it Into a sequence of mode lines. Keep track of the scan line count of your 
display by looking up the scan line requirements of the various modes In 
Figure 2.1. Translate the sequence of mode lines Into a sequence of ANTIC 
mode bytes. Put three 'blank 8 lines 1 bytes ($70) at the top of the list. 
Set bit 6 of the first display byte (that Is, make the upper nybble a 4). 
This makes a load memory scan command. Follow with two bytes which specify 
the address of the screen RAM (lo then hi). Then follow with the rest of 
the display bytes. At the end of your display list put In the JVB 
instruction ($41) and the address of the top of the display list. Now store 
all of these bytes into RAM. They can be anywhere you want; just make sure 
they don't overlay something else and your JVB points to the top of the 
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display list. The display list must not cross a 1K address boundary. If 
you absolutely must have It cross such a boundary, Insert a JMP Instruction 
Just In front of the boundary. The JMP Instruction's operand Is the address 
of the first byte on the other side of the boundary. Next you must turn off 
ANTIC for a fraction of a second while you rewrite Its display list pointer. 

Do this by writing a 0 Into SDMCTL at location $22F. Then store the 
address of the new display list Into $230 and $231 (lo then hi). Lastly, 
turn ANTIC back on with a $22 Into SDMCTL. During the vertical blank, while 
ANTIC Is quiet, the operating system will reload ANTIC'S program counter 
with these values. 



WRITING TO A CUSTOM DISPLAY LIST SCREEN 

Screen memory can be placed anywhere In the address space of the 
computer. Normally the display list specifies the beginning of the screen 

memory with the first display Instruction the Initial LMS Instruction. 

However, ANTIC can execute a new LMS Instruction with each display line of 
the display list If this Is desired. In this way Information from all over 
the address space of the computer can be displayed on a single screen. This 
can be of value In setting up Independent text windows. . 

There are several restrictions In your placement of the screen memory. 
First, screen memory cannot cross a 4K address boundary. If you cannot 
avoid crossing a 4K boundary (as would be the case In BASIC mode 8, which 
uses 8K of RAM) you must reload the memory scan counter with a new LMS 
Instruction. Second, If you wish to use any of the operating system screen 
routines you must abide by the conventions the OS uses. This can be 
particularly difficult when using a modified display list In a BASIC 
program. If you alter a standard display list from a BASIC program and then 
attempt to PRINT or PLOT to the screen, the OS will do so under the 
assumption that the display list Is unchanged. This will probably result In 
a garbled display. 

There are three ways the display can fall when you attempt this. 
First, BASIC may refuse to carry out a screen operation because It Is 
Impossible to do In the Graphics mode tha the OS thinks It Is In. The OS 
stores the value of the Graphics mode that It thinks Is on the screen In 
address $57. You can fool the OS Into cooperating by POKElng a different 
value there. POKE the BASIC mode number, not the ANTIC mode number. 

The second failure you might get arises when you mix mode lines with 
different screen memory byte requirements. Some mode lines require 40 bytes 
per line, some require 20 bytes per line, and some require only 10 bytes per 
line. Let's say that you Insert one 20 byte mode line Into a display list 
with 40 byte mode lines. Then you PRINT text to the display. Everything 
above the Interloper line Is fine, but below It the characters are shifted 
20 spaces to the right. This Is because the operating system assumed that 
each line would require 40 bytes and positioned the characters accordingly. 
But ANTIC, when It encountered the Interloper line, took only twenty bytes 
of what the OS thought should be a 40-byte line. ANTIC Interpreted the 
other 20 bytes as belonging to the next line, and displayed them there. 
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This resulted In the next line and all later lines being shifted 20 spaces 
to the right. 

The only absolute way around this problem Is to refrain from using 
BASIC PRINTS and PLOTs to output to a custom display list screen. The quick 
and dirty solution Is to organize the screen into line groups which contain 
Integer multiples of the standard byte requirement. That Is, do not Insert 
a 20-byte mode line Into a 40-byte display; Instead Insert two 20-byte lines 
or one 20-byte line and two 10-byte lines. So long as you retain the proper 
Integer multiples the horizontal shift will be avoided. 

This solution accentuates the third problem with mixed display lists 
and BASIC: vertical shifts. The OS positions screen material vertically by 
calculating the number of bytes to skip down from the top of the screen. In 
a standard 40-byte line display, BASIC would position the characters onto 
the tenth line by skipping 360 bytes from the beginning. If you have 
Inserted four 10-byte lines then BASIC will end up three lines further down 
the screen than you would otherwise expect. Furthermore, different mode 
lines consume different numbers of scan lines, so the position on the screen 
will not be quite what you expected If you do not take scan line costs Into 
account. 

As you can see, mixed mode displays can be difficult to use in 
conjunction with the OS. Often you must fool the operating system to make 
such displays work. To PRINT or PLOT to a mode window, POKE the BASIC mode 
number of that window to address $57, then POKE the address of the top left 
pixel of the mode window into locations $58 and $59 (lo then hi). In 
character modes, execute a POSITION 0,0 to home the cursor to the top left 
corner of the mode window. In map modes, all PLOTs and DRAWTOs wll I be made 
using the top left corner of the mode window as the origin of the coordinate 
system. 

The display list system can be used to produce appealing screen 
displays. Its most obvious use Is for mixing text and graphics. For 
example, you could prepare a screen with a bold BASIC mode 2 title, a medium 
size BASIC mode 1 subtitle, and small BASIC mode 0 fine print. You could 
then throw In a BASIC mode 8 picture In the middle with some more text at 
the bottom. A good example of this technique Is provided by the display In 
the States and Capitals program. 

The aforementioned problems will discourage the extensive use of such 
techniques from BASIC. With assembly language routines modified display 
lists are best used by organizing the screen into a series of windows, each 
window having its own LMS instruction and Its own Independent RAM area. 



APPLICATIONS OF DISPLAY LISTS 

One simple application of display list modifications Is to vertically 
space lines on the screen by Inserting blank line bytes. This will add some 
vertical spacing which will highlight critical messages and enhance the 
readability of some displays. 
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Another Important use of display list manipulations is In providing 
access to features not available from BASIC. There are three text modes 
supported by ANTIC that BASIC does not support. Only display list 
manipulations gain the user access to these modes. There are also display 
list Interrupt and fine scrolling capabilities that are only available after 
the display list Is modified. These features are the subjects of chapters 5 
and 6. 

Manipulations with the LMS Instruction and Its operand offer many 
possibilities to the creative programmer. For example, by changing the LMS 
during vertical blank the programmer can alternate screen images. This can 
be done at slow speed to change between predrawn displays without having to 
redraw each one. Each display would continue to reside In (and consume) RAM 
even while It Is not In use, but It would be available almost Instantly. 
This technique can also be used for animation. By flipping through a 
sequence of displays, cyclic animation can be achieved. The program to do 
this would manipulate only two address bytes to display many thousands of 
bytes of RAM. 

It Is also possible to superimpose Images by flipping screens at high 
speed. The human eye has a time resolution of about 1/16th of a second, so 
a program can cycle between four Images, one every 1/60th of a second, so 
that each repeats every 1/15th of a second. In this way, up to four Images 
can appear to reside simultaneously on the screen. Of course, there are 
some drawbacks to this method. First, four separate displays may well cost 
a lot of RAM. Second, each display Image will be washed out because it only 
shows up one quarter of the time. This means that the background of all 
displays must be black, and each Image must be bright. Furthermore, there 
will be some unpleasant screen flicker when this technique Is used. A 
conservative programmer might consider cycling between only three or even 
only two Images. This technique can also be used to extend the color and 
luminosity resolution of the computer. By cycling between four versions of 
the same Image, each version stressing one color or luminosity range, a 
wider range of colors and luminosities Is avalllble. For example, suppose 
we wish to display a bar of many different luminances. We first set our 
four color registers to the values: 



background: 00 

playfleld Is 02 

playfield 2: OA 

playfleld 3: 0C 
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Now we put the following Images into each of the screen RAM areas: 



first frame 


1 


1 


1 


1 


2 


3 


2 


3 


2 


3 


2 
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second frame 


B 


1 


1 


1 
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third frame 
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fourth frame 
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B 
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B 


B 
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effective luminance 
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4 


6 


8 


10 


12 


20 


24 


30 


36 


40 


48 



perceived I umi nance 



Eilllllll 




In this way much finer luminance resolution Is possible, 

A final suggestion concerns a subject which is laden with opportuniti 
but little understood as yet: the dynamic display list. This Is a display 
list which the 6502 changes during vertical blank periods, it should be 
possible to produce Interesting effects with dynamic display lists. For 
example, a text editing program dynamically Inserts blank lines above and 
below the screen line being edited to set it apart from the other lines of 
text. As the cursor is moved vertically, the display list is changed. The 
technique is odd but very effective. 
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CHAPTER 3 
GRAPHICS INDIRECTION 
(COLOR REGISTERS AND CHARACTER SETS) 

Indirection Is a powerful concept In computing but a difficult one for the 
beginning programmer to appreciate. In 6502 assembly language there are three 
levels of Indirection In referring to numbers. The first and most direct 
level Is the Immediate addressing mode In which the number Itself Is directly 
stated: 

LDA #$F4 

The second level of Indirection Is reached when the program refers to a 
memory location that holds the number: 

LDA $0602 

The third and highest level of Indirection with the 6502 Is attained when the 
program refers to a pair of memory locations which together contain the 
address of the memory location which holds the number. In the 6502, this 
indirection Is complicated by the addition of an Index: 

LDA ($D0),Y 

Indirection provides a greater degree of generality (and hence power) to the 
programmer. Instead of trucking out the same old numbers every time she wants 
to get something done, the programmer can simply point to them. By changing 
the pointer, she can change the behavior of the program. Indirection Is 
obviously an important capability. 

Graphics indirection is built Into the ATARI Personal Computer System In 
two ways: with color registers and with character sets. Programmers first 
approaching this computer after programming other systems often think in 
terms of direct colors. A color register Is a more complex beast than a 
color. A color specifies a permanent value. A color register is Indirect; It 
holds any color value. The difference between the two Is analogous to the 
difference between a box-end wrench and a socket wrench. The box-end wrench 
comes In one size only but a socket wrench can hold almost any size socket. A 
socket wrench is more flexible but takes a little more skill to utilize 
properly. Similarly, a color register Is more flexible than a color but takes 
more skill to use effectively. 

There are nine color registers In the ATARI 400/800; four are for 
player-missile graphics and will be discussed In Chapter 4. The remaining 
five are not always used; depending on the graphics mode used as few as 2 
registers or as many as 5 will show up on the screen. In BASIC mode 0 only 
one and one-half registers are used because the hue value of the characters 
is Ignored; characters take the same hue as playfleld register 2 but take 
their luminosity from register 1. The color registers are In CTIA at 
addresses $D016 through $D01A. They are f shadowed f from OS RAM locations Into 
CTIA during vertical blank. Figure 3.1 gives color register shadow and 
hardware addresses. 
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IMAGE 



HARDWARE 
LABEL ADDRESS 



OS SHADOW 
LABEL ADDRESS 



CONTROLLED 
player 0 
player 1 
player 2 
pi ayer 3 
playfleld 0 
playfleld 1 
playfleld 2 
playfleld 3 
background 



COLPMO DO 12 

COLPM1 D013 

C0LPM2 DO 14 

C0LPM3 D0 15 

COLPFO DO 16 

COLPF1 D0 17 

C0LPF2 D018 

C0LPF3 DO 19 

COLBK D01A 



PCOLRO 2C0 

PCOLR1 2C1 

PC0LR2 2C2 

PCOLR3 2C3 

COLORO 2C4 

COLOR 1 2C5 

C0L0R2 2C6 

C0L0R3 2C7 

C0L0R4 2C8 



Figure 3.1 
color register labels and addresses 



For most purposes, the user controls the color registers by writing to 
the shadow locations. There are only two cases In which the programmer would 
write directly to the CTIA addresses. The first and most common is the 
display list Interrupt which will be taken up In Chapter 5. The second 
arises when the user disables the OS vertical blank Interrupt routines which 
move the shadow values Into CTIA. Vertical blank Interrupts are the subject 
of Appendix I . 

Colors are encoded In a color register by a simple formula. The upper 
nybble gives the hue value, which Is Identical to the second parameter of 
the BASIC SETCOLOR command. Table 9.3 of the BASIC Reference Manual lists 
hue values. The lower nybble In the color register gives the luminosity 
value of the color. It Is the same as the third parameter In the BASIC 
SETCOLOR command. The lowest order bit of this nybble Is not significant. 
Thus, there are eight luminosities for each hue. There are a total of 128 
colors from which to choose (8 luminosities times 16 hues). In this book, 
the term 'color 1 denotes a hue-lumlnos ity combination. 

Once a color Is encoded Into a color register It Is mapped onto the 
screen by referring to the color register that holds It. In map display 
modes which support four color registers the screen data specifies which 
color register Is to be mapped onto the screen. Since there are four color 
registers It takes only two bits to encode one pixel. Thus, each screen data 
byte holds data for four pixels. The value In each pair of bits specifies 
which color register provides the color for that pixel. 

In text display modes (BASIC'S GRAPHICS modes 1 and 2) the selection of 
color registers Is made by the top two bits of the character code. This of 
course leaves only 6 bits for defining the character, which Is why these two 
modes have only 64 characters available. 

Color register Indirection gives the programmer four special 
capabilities. First, the programmer can choose from 128 different colors for 
his displays. This allows him to choose the color which most nearly meets 
his needs. 
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Second, the programmer can manipulate the color registers In real time 
to produce pretty effects. The simplest version of this Is demonstrated by 
the fol lowing BASIC I Ine: 

FOR 1=0 TO 254 STEP 2:P0KE 712,I:NEXTI 

This line simply cycles the border color through all possible colors. The 
effect Is quite pleasing and certainly grabs attention. The fundamental 
technique can be extended In a variety of ways. A special variation of this 
Is to create simple cyclic animation by drawing a figure In four colors and 
then cycling the colors through the color registers rather than redrawing 
the figure. The following program Illustrates the Idea: 



10 GRAPHICS 23 

20 FOR X=0 TO 39 

30 FOR 1=0 TO 3 

40 COLOR I 

50 PLOT 4*X+I,0 

60 DRAWT0 4*X+I,95 

70 NEXT I 

80 NEXT X 

90 A=PEEK(712) 

100 POKE 712,PEEK(710) 

110 POKE 710,PEEK(709) 

120 POKE 709,PEEK(708) 

130 POKE 708, A 

140 GOTO 90 



The third application of color registers Is to logically key colors to 
situations. For example, a paged menu system can be made more understandable 
by changing the background color or the border color for each page In the 
menu. Perhaps the screen could flash red when an Illegal key Is pressed. The 
use of the color characters available In BASIC Graphics modes 1 and 2 can 
greatly extend the Impact of textual material. An account sum could be shown 
In red If the account is In the red, or black if the account Is In the 
black. Words or phrases of import can be shown in special colors to make 
them stand out. The use of colors In map modes (no text) can also Improve 
the utility of such graphics. A single graphics Image (a monster, a boat, or 
whatever) could be presented In several different colors to represent 
several different versions of the same thing. It costs a great deal of RAM 
to store an Image, but It costs very little to change the color of an 
existing Image. For example, it would be much easier to show three different 
boats by presenting one boat shape In three different colors than three 
different boat shapes. 

The fourth and most Important application of color registers Is 
utilized with display list Interrupts. A single color register can be used 
to put up to 128 colors onto a single screen. This very important capability 
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will be discussed In Chapter 5. 
CHARACTER SETS 

Graphics Indirection Is also provided through the redeflnable character 
set. A standard character set Is provided In ROM, but there Is no reason why 
this particular character set must be used. The user can create and display 
any character set she desires. There are three steps necessary to use a 
redefined character set. First, the programmer must define the character 
set. This Is the most time-consuming step. Each character Is displayed on 
the screen on an 8x8 grid; It Is encoded In memory as an 8-byte table. 
Figure 3.2 depicts the encoding arrangement. 



representation 
00 
18 
3C 
66 
66 

7E 
66 

00 

Figure 3.2 
character encoding 

A full character set has 128 characters In It, each with a normal and 
an Inverse video Incarnation. Such a character set needs 1024 bytes of space 
and must start on a 1K boundary. Character sets for BASIC modes 1 and 2 have 
only 64 distinct characters, and so require only 512 bytes and must start on 
a 1/2K boundary. The first eight bytes define the zeroth character, the next 
eight bytes define the first character, and so on. Obviously, defining a new 
character set Is a big job. Fortunately, there are software packages on the 
market to make this job easier. 

Once the character set Is defined and placed Into RAM, you must tell 
ANTIC where It can find the character set. This Is done by poking the page 
number of the beginning of the character table Into location $D409 (decimal 
54281). The OS shadow location, which Is the location one would normally 
use, Is called CHBAS and resides at $2F4 (decimal 756). The third step In 
using character sets Is to print the character you want onto the screen. 
This can be done directly from BASIC with simple PRINTs or by writing 
numbers directly Into the screen memory. 

A special capability of the system not supported In BASIC Is the 
4-color character set option. BASIC Graphics modes 1 and 2 support 5 colors, 
but each character in these modes Is really a two-color character; each one 
has a foreground color and a background color. The foreground color can be 
any of four single colors, but only one color at a time can be shown within 
a single character. This can be a serious hindrance when using character 



character Image 




binary representation 
00000000 
00011000 
00111100 
01100110 
01100110 
01111110 
01100110 
00000000 



hex 
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graphics* There are two other text modes designed especially for character 
graphics. They are ANTIC modes 4 and 5. Each character In these modes Is 
only four pixels wide, but each pixel can have four colors (counting 
background). The characters are defined just like BASIC Graphics mode 0 
characters, except that each pixel Is twice as wide and has two bits 
assigned to It to specify the color register used. Unlike ANTIC modes 6 and 
7 (BASIC modes 1 and 2), color register selection Is not made by the 
character name byte but Instead by the defined character set. Each byte In 
the character table Is broken Into four bit pairs, each of which selects the 
color for a pixel. (This Is why there are only four horizontal pixels per 
character.) The highest bit (D7) of the character name byte modifies the 
color register used. Color register selection Is made according to Figure 
3.3: 

bit pair In D7 = 0 D7 = 1 

character defn 

00 
01 
10 
11 

Figure 3.3 
color register selection for characters 



COLBAK COLBAK 

PFO PFO 

PF1 PF1 

PF2 PF3 



Using these text modes, multicolored graphics characters can be put 
onto the screen. 

Another Interesting ANTIC character mode Is the lowercase descenders 
mode (ANTIC mode 3). This mode displays 10 scan lines per mode line, but 
since characters use only 8 bytes vertically, the lower two scan lines are 
normally left empty. If a character In the last quarter of the character set 
Is dtsplayed, the top two scan lines of the character will be left empty; 
the data that should have been displayed there will Instead be shown on the 
bottom two lines. This allows the user to create lowercase characters with 
descenders . 

Many Interesting and useful application possibilities spring from 
character set Indirection. The obvious application Is the modified font. A 
different font can give a program a unique appearance. It Is possible to 
have Greek, Cyrillic, or other special character sets. Going one step 
further, one can create graphics fonts. The ENERGY CZAR™ computer program 
uses a redefined character set for bar graphs. A character occupies eight 
pixels; this means that bar charts Implemented with standard characters have 
a resolution of eight pixels, a rather poor resolution. ENERGY CZAR uses a 
special character set In which some of the less popular text symbols 
(ampersands, pound signs, etc) have been replaced with special bar chart 
characters. One character Is a one-pixel bar, another is a two-pixel bar, 
and so on to the full eight-pixel bar. The program can thus draw detailed 
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bar charts with resolution of a single pixel. Figure 3.4 shows a typical 
display from this program. The mix of text with map graphics Is only 
apparent; the entire display Is constructed with characters. 



M r> R 31 GE "3 CBS/QUAD) 




Figure 3.4 
ENERGY CZAR W bar charts 



In many applications character sets can be created that show special 
Images. For example, by defining a terrain graphics character set with river 
characters, forest characters, mountain characters, and so forth, It Is 
possible to make a terrain map of any country. Indeed, with imagination a 
map of terrain on a different planet can just as easily be done. When doing 
this, It Is best to define five to eight characters for each terrain type. 
Each variation of a single type should be positioned slightly differently In 
the character pixel. By mixing the different characters together It Is 
possible to avoid the monotonous look that is characteristic of primitive 
character graphics. Most people won't realize that the resulting map uses 
character graphics until they study the map closely. Figure 3.5 shows a 
display of a terrain map created with character set graphics. The 
reproduction in black and white does not do justice to the original display, 
which has up to 18 colors. 
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Figure 3.5 
terrain map with character set graphics 



One could create an electronics character set with transistor 
characters, diode characters, wire characters, and so forth to produce an 
electronics schematics program. Or one could create an architectural 
character set with doorway characters, wall characters, corner characters, 
and so on to make an architectural blueprint program. The graphics 
possibilities opened up by character graphics with personal computers have 
not been fully explored. 

Characters can be turned upside down by POKEing a 4 Into location 755. 
One possible application of this feature might be for displaying playing 
cards (as In a Blackjack game). The upper half of the card can be shown 
rlghtside up; with a display list Interrupt the characters can be turned 
upside down for the lower half of the card. This feature might also be of 
some use In displaying Images with mirror reflections (reflection pools, 
lakes, etc). 

Even more exciting possibilities spring to mind when one realizes that 
It Is quite practical to change character sets while the program Is running. 
A character set costs either 512 bytes or 1024 bytes; in either case It Is 
quite Inexpensive to keep multiple character sets In memory and flip between 
them during program execution. There are three time regimes for such 
character set multiplexing: human slow (more than 1 second); human fast 
(1/60th second to 1 second); and machine fast (faster than 1/60th second). 
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Human slow character set multiplexing Is useful for 'change of scenery' 
work. For example, a space travel program might use one graphics character 
set for one planet, another set for space, and a third set for another 
planet. As the traveler changes locations, the program changes the character 
set to give exotic new scenery. An adventure-type program might change 
character sets as the player changes locales. 

Human fast character set multiplexing Is primarily of value for 
animation. This can be done In two ways: changing characters within a single 
character set, and changing whole character sets. The SPACE INVADERS 
(trademark of Talto America Corp.) on the ATARI 400/800 uses the former 
technique. The Invaders are actually characters. By rapidly changing the 
characters, the programmer was able to animate them. This was easy because 
there are only six different monsters; each has 4 different Incarnations. 
High speed cyclic animation of an entire screen Is possible by setting up a 
number of character sets, drawing the screen image, and then simply cycling 
through the character sets. If each character has a slightly different 
Incarnation in each of the character sets, that character will go through an 
animated sequence as the character sets are changed. In this way a screen 
full of objects could be made to cycllcly move with a very simple loop. Once 
the character set data Is In place and the screen has been drawn the code to 
animate the screen would be this simple: 

1000 FOR 1=1 TO 10 
1010 POKE 756,CHARBASE(I) 
1020 NEXT I 
1030 GOTO 1000 



Computer fast character set animation Is used to put multiple character 
sets onto a single screen. This makes use of the display list Interrupt 
capability of the computer. This topic will be addressed further In Chapter 
5. 

The use of character sets for graphics and animation has many 
advantages and some limitations. The biggest advantage Is that It costs very 
little RAM to produce detailed displays. A graphics display using BASIC mode 
2 characters (such as the one shown In Figure 3.5) can give as much detail 
and one more color than a BASIC mode 7 display, and yet the character Image 
will cost 200 bytes while the map Image will cost 4000 bytes. The RAM cost 
for multiple character sets Is only 512 bytes per set, so it Is Inexpensive 
to have multiple character sets. Screen manipulations with character 
graphics are much faster because you have less data to manipulate. However, 
character graphics are not as flexible as map graphics. You cannot put 
anything you want anywhere on the screen. This limitation would preclude the 
use of character graphics In some applications. However, there remain many 
graphics applications for which the program need display only a limited 
number of predefined shapes In fixed locations. In these cases character 
graphics provide great utility. 
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PLAYER-MISSILE GRAPHICS 



Animation is an important capability of any personal computer system. 
Activity on the screen can greatly add to the excitement and realism of any 
program. Certainly animation is crucial to the appeal of many computer games. 
More Important, an animated image can convey Information with more Impact and 
clarity than a static image. It can draw attention to an Item or event of 
importance. It can directly show a dynamic process rather than Indirectly 
talk about It. Animation must accordingly be regarded as an Important element 
of the graphics capabilities of any computer system. 

The conventional way to effect animation with personal computers Is to 
move the image data through the screen RAM area. This requires a two-step 
process. First, the program must erase the old image by writing background 
values to the RAM containing the current Image. Then the program must write 
the image data to the RAM corresponding to the new position of the Image. By 
repeating this process over and over, the image will appear to move on the 
screen . 

There are two problems with this technique. First, if the animation is 
being done in a graphics mode with large pixels, the motion will not be 
smooth; the image will jerk across the screen. With other computers the only 
solution is to use a graphics mode with smaller pixels (higher resolution). 
The second problem Is much worse. The screen Is a two-dimensional image but 
the screen RAM Is organized one-d imens ional ly . This means that an image which 
is contiguous on the screen will not be contiguous in the RAM. The 
discrepancy is illustrated In Figure 4.1. 



I MAGE Correspond I ng 

bytes In RAM 

00 00 00 

00 99 00 

00 BD 00 

00 FF 00 

00 BD 00 

00 99 00 

00 00 00 

spacing of bytes In RAM: 

00 00 00 00 99^00^00^ 00 00 00 00 

Image bytes scattered through RAM 

Figure 4.1 
RAM images are not contiguous 




The significance of this discrepancy does not become obvious until you 
try to write a program to move such an image. Look how the bytes that make 
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up the image are scattered through the RAM. To erase them your program must 
calculate their addresses. This calculation Is not always easy to do. The 
assembly code just to access a single screen byte at screen location 
(XPOS,YPOS) would look like this (this code assumes 40 bytes per screen 
I ine): 



LDA SCRNRM 
STA POINTR 
LDA SCRNRM+1 
STA POINTR+1 
LDA #$00 
STA TEMPA+1 
LDA YPOS 
ASL A 

ROL TEMPA+1 
ASL A 

ROL TEMPA+1 
ASL A 

ROL TEMPA+1 
LDX TEMPA+1 
STX TEMPB+1 
STA TEMB 
ASL A 

ROL TEMPA+1 
ASL A 

ROL TEMPA+1 
CLC 

ADC TEMPB 

STA TEMPB 
LDA TEMPA+1 
ADC TEMPB+1 
STA TEMPB+1 
LDA TEMPB 
CLC 
ADC POINTR 
STA POINTR 
LDA TEMPB+1 
ADC POINTR+1 
STA POINTR+1 
LDY XPOS 
LDA (P0INTR),Y 



Address of beginning of screen RAM 
zero page pointer 
high order byte of address 
high order pointer 

temporary register 
vertical position 
times 2 

shift carry Into TEMPA+1 
times 4 

sh I f t carry agal n 
times 8 
shift again 
save YP0S*8 
into TEMPB 
low byte 
times 16 

times 32 



add In YP0S*8 to get YP0S*40 
now do high order byte 



TEMPB contains the offset from top of screen to pixel 



Clearly 
Is certain ly 
certainly a 
make the cod 
pixels on a 
100 machine 
that occupl 
machine eye I 
I f you want 
ml I I I seconds 



, this code to access a screen location Is too cumbersome. This 
not the most elegant or fastest code to solve the problem; 
good programmer could take advantage of special circumstances to 
e more compact or elegant. The point of this Is that accessing 
screen takes a lot of computing. The above routine takes about 
cycles to access a single byte on the screen. To move an image 

, say, 50 bytes, would require 100 accesses or about 10,000 
es or roughly 10 milliseconds. This may not sound like much but 
to achieve smooth motion you have to move the object every 17 
If there are other objects to move or any calculations to 
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carry out there Isn't much processor time left to devote to them. What this 
all adds up to Is that this type of animation (called f playfield animation') 
Is too slow for many purposes. You can still get animation this way, but 
you are limited to few objects or small objects or slow motion or few 
calculations between motion. The trade-offs that a programmer must make In 
using such animation are too restrictive. 

The ATARI 400/800™ solution to this problem Is player-missile graphics. 
In order to understand player-missile graphics, It Is important to 
understand the essence of the problem of playfield animation: the screen 
image Is two-dimensional while the RAM image Is one-d Imens lona I . The 
solution was to create a graphics object which is one-d Imens I ona I on the 
screen as well as one-d Imens lona I In RAM. This object (called a player) 
appears In RAM as a table that is either 128 or 256 bytes long. The table 
Is mapped directly to the screen. It appears as a vertical band stretching 
from the top of the screen to the bottom. Each byte in the table is mapped 
into either one or two horizontal scan lines, with the choice between the 
two made by the programmer. The screen image Is a simple bit-map of the 
data In the table. If a bit Is on, then the corresponding pixel In the 
vertical column Is lit; If the bit Is off, then the corresponding pixel Is 
off. Thus, the player image Is not strictly one-dimensional; It Is actually 
eight bits wide. 

Drawing a player Image on the screen is quite simple. First you draw a 
picture of the desired image on graph paper. This image must be no more 
than 8 pixels wide. Then you translate the Image Into binary code, 
substituting ones for Illuminated pixels and zeros for empty ones. Then you 
translate the resulting binary number into decimal or hexadecimal, depending 
on which Is more convenient Then you store zeros Into the player RAM to 
clear the image. Next, store the image data Into the player RAM, with the 
byte at the top of the player image going first, followed by the other Image 
bytes In top to bottom sequence. The further down In RAM you place the 
data, the lower the image will appear on the screen. 

Animating this Image Is very easy. Vertical motion Is obtained by 
moving the image data through the player RAM. This Is In principle the same 
method used In playfield animation, but there Is a big difference in 
practice: the move routine for vertical motion Is a one-d Imens lona I move 
instead of a two-dimensional move. The program does not need to multiply by 
40 and It often does not need to use Indirection. It could be as simple as: 



LDX #$01 
LOOP LDA PLAYER, X 

STA PLAYER-1,X 
I NX 

BNE LOOP 



This routine takes about 4 milliseconds to move the entire player, about 
half as long as the playfield animation routine which actually moves only 50 
bytes where this one moves 256 bytes. If high speed Is necessary, the loop 
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can be trimmed to move only the Image bytes themselves rather than the whole 
player; then the loop would easily run In about 100-200 microseconds. The 
point here Is that vertical motion with players Is both simpler and faster 
than motion with playfleld objects. 

Horizontal motion Is even easier than vertical motion. There Is a 
register for the player called the horizontal position register. The value 
In this register sets the horizontal position of the player on the screen. 
All you do Is store a number Into this register and the player jumps to that 
horizontal position. To move the player horizontally simply change the 
number stored In the horizontal position register. That's all there Is to 
It. 

Horizontal and vertical motion are Independent; you can combine them In 
any fashion you choose. 

The scale for the horizontal position register Is one color clock per 
unit. Thus, adding one to the horizontal position register will move the 
player one color clock to the right. There are only 228 color clocks In a 
single scan line; furthermore, some of these are not displayed because of 
overscan. The horizontal position register can hold 256 positions; some of 
these are off the left or right edge of the screen. Depending on the 
overscan of the television, positions 0 through 44 will be off the left edge 
of the screen and positions 220 through 255 will be off the right edge. 
Thus, the visible region of the player Is In horizontal positions 44 through 
220. Remember, however, that this may vary from television to television; a 
conservative range Is from 60 to 200. This coordinate range can sometimes 
be clumsy to use, but It does offer a nice feature: a simple way to remove a 
player from the screen is to set the player's horizontal position to zero. 
With a single load and store In assembly (or a single POKE In BASIC), the 
pl ayer will disappear. 

The system described so far makes It possible to produce high-speed 
animation. There are a number of embellishments which greatly add to Its 
overall utility. The first embellishment is that there are four Independent 
players to use. These players all have their own sets of control registers 
and RAM area; thus their operation Is completely Independent. They are 
labelled P0 through P3. They can be used side by side to give up to 32 bits 
of horizontal resolution, or they can be used Independently to give four 
movable objects. Each player has Its own color register; this color 
register Is completely Independent of the playfleld color register. The 
player color registers are called C0LP(X) an are shadowed at PCOLR(X) . This 
gives you the capability to put much more color onto the screen. However, 
each player has only one color; multicolored players are not possible 
without display list interrupts (display list Interrupts are discussed In 
Chapter 5). Each player has a controllable width; you can set It to have 
normal width, double width, or quadruple width with the SIZEP(X) registers. 
This Is useful for making players take on different sizes. You also have 
the option of choosing the vertical resolution of the players. You can use 
single- line resolution, In which each byte In the player table occupies one 
horizontal scan line, or double- line resolution, In which each byte occupies 
two horizontal scan lines. With single- line resolution, each player bit-map 
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table Is 256 bytes long; with double- line each table Is 128 bytes long. 
This Is the only case where player properties are not Independent; the 
selection of vertical resolution applies to all players. Player vertical 
resolution Is controlled by bit D4 of the DMACTL register. In double- line 
resolution, the first twn or so bytes In the player table area are lost to 
vertical overscan and are off the top edge of the screen. The last twenty 
or so bytes are lost off the bottom edge of the screen. In single- line 
resolution, twenty and forty bytes are lost correspondingly. 

The next embellishment Is the provision of missiles. These are two-bit 
wide graphics objects associated with the players. There Is one missile 
assigned to each player; It takes its color from the player's color 
register. Missile shape data comes from the missile bit-map table in RAM 
just In front of the player tables. All four missiles are packed Into the 
same table (four missiles times two bits per missile gives eight bits). 
Missiles can move Independently of players; they have their own horizontal 
position registers. Missiles have their own size register, SIZEM, which can 
set the horizontal width just like the SIZEP(X) registers do for players. 
However, missiles cannot be set to different sizes; they are all set 
together. Missiles are useful as bullets or for skinny vertical lines on 
the screen. If desired, the missiles can be grouped together Into a fifth 
player, In which case they take the color of playfield color register 3. 
This Is done by setting bit D4 of the priority control register (PRIOR). 
Note that missiles can still move Independently when this option Is In 
effect; their horizontal positions are set by their horizontal position 
registers. The fifth player enable bit only affects the color of the 
missiles. 

You move a missile vertically the same way that you move a player: by 
moving the missile Image data through the missile RAM area. This can be 
difficult to do because missiles are grouped Into the same RAM table. To 
access a single missile you must mask out the bits for the other missiles. 

An Important feature of playei — missile graphics Is that players and 
missiles are completely Independent of the playfield. You can mix them with 
any graphics mode, text or map. This raises a problem: what happens If a 
player ends up on top of some playfield Image? V/hlch image has priority? 
You have the option to define the priorities used In displaying players. If 
you wish, all players can have priority over all playfield color registers. 
Or you can set all playfield color registers (except background) to have 
priority over all players. Or you can set player 0 and player 1 (henceforth 
referred to as PO and P1 ) to have priority over all playfield color 
registers, with P2 and P3 having less priority than the playfield. Or you 
can set playfield color registers 0 and 1 (PFO and PF1 ) to have priority 
over all players, which then have priority over PF2 and PF3. These 
priorities are selected with the priority control register (PRIOR) which is 
shadowed at GPRIOR. This capability allows a player to pass In front of of 
one image and behind another, allowing three-dimensional effects. 

The final embellishment is the provision for hardware collision 
detection. This Is primarily of value for games. You can check if any 
graphics object (player or missile) has collided with anything else. 
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Specifically, you can check for miss 1 1 e-p I ayer collisions, miss i I e-p I ayf le I d 
collisions, player-player collisions, and pi ayer-pl ayf lei d collisions. 
There are 54 possible collisions, and each one has a bit assigned to it that 
can be checked. If the bit Is set, a collision has occurred. These bits 
are mapped Into 15 registers In CTIA (only the lower 4 bits are used and 
some are not meaningful). These are read-only registers; they cannot be 
cleared by writing zeros to them. The registers can be cleared for further 
collision detection by writing any value to register HITCLR. All collision 
registers are cleared by this command. 

In hardware terms, collisions occur when a player image coincides with 
another Image; thus, the collision bit will not be set until the part of the 
screen showing the collision Is drawn. This means that collision detection 
might not occur until as much as 16 milliseconds have elapsed since the 
player was moved. The preferred solution Is to execute player motion and 
collision detection during the vertical blank Interrupt routine (see 
Appendix I). In this case collision detection should be checked first, then 
collisions cleared, then players moved. Another solution Is to wait at 
least 16 milliseconds after moving a player before checking for a collision 
Involving that player. 

There are a number of steps necessary to use p I ayer-mlss 1 1 e graphics. 
First you must set aside a p I ayer-mt ss 1 1 e RAM area and tell the computer 
where it Is. If you use single- line resolution, this RAM area will be 1280 
bytes long; If you use double- line resolution It will be 640 bytes long. A 
good practice is to use the RAM area just in front of the display area at 
the top of RAM. The layout of the pi ayer-mlss I le area Is shown in Figure 
4.2. 
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Figure 4.2 
player-missile RAM area layout 



The pointer to the beginning of the player-missile area is labelled 
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PMBASE. Because of internal limitations of ANTIC, PMBASE must be on a 1K 
boundary for single line resolution, or a 2K boundary for double line 
resolution. If you elect not to use all of the players or none of the 
missiles, the areas of RAM set aside for the unused objects may be used for 
other purposes. Once you have decided where your p I ayer-mlss 1 1 e RAM area 
will be, you Inform ANTIC of this by storing the page number of PMBASE Into 
the PMBASE register In ANTIC. 

The next step Is to clear the player and missile RAM by storing zeros 
Into all locations In the pi ayer-mtssl le RAM area. Then draw the players 
and missiles by storing image data Into the appropriate locations In the 
player-missile RAM area. 

Next, set the player parameters by setting the player color, horizontal 
position, and width registers to their Initial values. If necessary, set 
the player/playf ield priorities. Inform ANTIC of the vertical resolution 
you desire by setting bit D4 of register DMACTL (shadowed at SDMCTL) for 
single- line resolution, and clearing the bit for double- line resolution. 
Finally, enable the players by setting the PM DMA enable bit In DMACTL. Be 
careful not to disturb the other bits In DMACTL. A sample BASIC program for 
setting up a player and moving it with the joystick Is given below: 

1 PMBASE=54279:REM player-missile base pointer 

2 RAMTOP= 1 06 : REM OS top of RAM pointer 

3 SDMCTL=559:REM RAM shadow of DMACTL register 

4 GRACTL=53277 : REM CTIA graphics control register 

5 HP0SP0=53248:REM horizontal position of P0 

6 PCOLR0=704:REM shadow of player 0 color 

10 GRAPHICS 0:SETCOLOR 2, 0,0: REM set background color to black 

20 X=100:REM BASIC'S player horizontal position 

30 Y=48:REM BASIC'S player vertical position 

40 A=PEEK ( RAMT0P ) -8 : REM get RAM 2K below top of RAM 

50 POKE PMBASE, A:REM tell ANTIC where PM RAM Is 

60 MYPMBASE= : 256*A: REM keep track of PM RAM address 

70 POKE SDMCTL, 46:REM enable PM DMA with 2-line res 

80 POKE GRACTL,3:REM enable PM display 

90 POKE HPOSP0,100:REM declare horizontal position 

100 FOR l=MYPMBASE+512 TO MYPMBASE+640: REM this loop clears player 

110 POKE l,0 

120 NEXT I 

130 FOR l=MYPMBASE+512+Y TO MYPMBASE+51 8+Y 

140 READ A: REM this loop draws the player 

150 POKE I, A 
160 NEXT I 

170 DATA 8,17,35,255,32,16,8 

180 POKE PCOLR0,88:REM make the player pink 

190 A=STlCK(0) :REM read joystick 

200 IF A=15 THEN GOTO 190: REM If Inactive, try again 

210 IF A=11 THEN X=X-1 :P0KE HP0SP0,X 

220 IF A=7 THEN X=X+1:P0KE HP0SP0,X 

230 IF A<>13 THEN GOTO 280 
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240 FOR 1=8 TO 0 STEP -1 

250 POKE MYPMBASE+512+Y+I # PEEK(MYPMBASE+511+Y+I) 
260 NEXT I 
270 Y=Y+1 

280 IF A<> 14 THEN GOTO 190 
290 FOR 1=0 TO 8 

300 POKE MYPMBASE+511+Y+I,PEEK(MYPMBASE+512+Y+D) 
310 NEXT I 
320 Y=Y-1 
330 GOTO 190 



Once players are displayed, they can be difficult to remove from the 
screen. This Is because the procedure by which they are displayed Involves 
several steps. First, ANTIC retrieves player-miss I le data from RAM (If such 
retrieval Is enabled In DMACTL). Then ANTIC ships the player-missile data 
to CTIA (If such action Is enabled In GRACTL). CTIA displays whatever Is In 
Its player and missile graphics registers (GRAFP0 through GRAFP3 and GRAFM) . 
Many programmers attempt to turn off p I ayer-ml ss 1 1 e graphics by clearing 
the control bits In DMACTL and GRACTL. This only prevents ANTIC from 
sending new player-missile data to CTIA; the old data in the GRAF(X) 
registers will still be displayed. To completely clear the players the 
GRAF ( X ) registers must be cleared after the control bits In DMACTL and 
GRACTL have been cleared. A simpler solution Is to leave the player up but 
set Its horizontal position to zero. Of course, If this solution Is used, 
ANTIC will continue to use DMA to retrieve player-missl le data, wasting 
roughly 10,000 machine cycles per second. 

Playei — missile graphics allow a number of very special capabilities. 
They are obviously of great value In animation. They do have limitations: 
there are only four players and each Is only eight bits wide. If you need 
more bits of horizontal resolution you can always fall back on playfield 
animation. But for high speed animation or quick and dirty animation 
player-missile graphics work very well. 

It Is possible to bypass ANTIC and write player-missile data directly 
Into the player-missile graphics registers (GRAFP(X) ) In CTIA. This gives 
the programmer more direct control over p I ayer-mlss I le graphics. It also 
Increases his responsibilities concomitantly. The programmer must maintain 
a bit map of player-missile data and move It Into the graphics registers at 
th appropriate times. The 6502 must therefore be slaved to the screen 
drawing cycle. (See the discussion of kernels In Chapter 5.) This Is a 
clumsy technique that offers minor performance improvements In return for 
major programming efforts. The programmer who bypasses the hardware power 
offered by ANTIC must make up for it with his own sweat. 

Player-missile graphics offer many capabilities In addition to 
animation. Players are an excellent way to Increase the amount of color In 
a display. The four additional color registers they provide allow four more 
colors on each line of the display. Of course, the eight-bit resolution 
does limit the range of their application. There Is a way around this that 



4-8 



PLAYER-MISSILE GRAPHICS 



can sometimes be used. Take a player at quadruple width and put It onto the 
screen. Then set the priorities so that the player has lower priority than 
a playfield color. Next reverse that playfleld color with background, so 
that the apparent background color of the screen is really a playfleld 
color. The player disappears behind this new false background. Now cut a 
hole In the false background by drawing true background on it. The player 
will show up In front of the true background color, but only in the area 
where true background has been drawn. In this way the player can have more 
than eight bits of horizontal resolution. A sample program for doing this 
Is: 



100 POKE PMBASE,A 
110 MYPMBASE=256*A 
120 POKE SDMCTL,46 
130 POKE GRACTL,3 
140 POKE HPOSP0,100 

150 FOR l=MYPMBASE+512 TO MYPMBASEt640 

160 POKE I, 255: REM make player solid color 

170 NEXT I 

180 POKE PC0LR0,88 

190 POKE SIZEP0,3:REM set player to quadruple width 

200 POKE GPRI0R,4:REM set priority 

210 COLOR 4 

220 FOR Y=30 TO 40 

230 PLOT Y+22,Y 

240 DRAWTO Y+43,Y 

250 NEXT Y 



1 RAMT0P=106:REM 

2 PMBASE=54279:REM 

3 SDMCTL=559:REM 

4 GRACTL=53277:REM 

5 HP0SP0=53248:REM 

6 PC0LR0=704:REM 

7 SIZEP0=53256:REM 

8 GPRI0R=623:REM 
10 GRAPHICS 7 

20 SETCOLOR 4,8,4 
30 SETCOLOR 2,0,0 
40 COLOR 3 

50 FOR Y=0 TO 79: REM 
60 PLOT 0,Y 
70 DRAWTO 159,Y 
80 NEXT Y 

90 A=PEEK ( RAMT0P ) -20 : REM 



OS top of RAM pointer 

ANTIC player-missile RAM pointer 

shadow of DMACTL 

CTIA graphics control register 

horizontal position register of P0 

shadow of player 0 color register 

player width control register 

priority control register 



this loop fills the screen 



must back up further for GR. 7 
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Figure 4.3 
masking a player for more resolution 

Another application of player-missile graphics Is for special 
characters. There are many special types of characters that cross vertical 
boundaries In normal character sets. One way to deal with these is to 
create special character sets that address this problem. Another way is to 
use a player. Subscripts, Integral signs, and other special symbols can be 
done this way. A sample program for doing this is: 



1 RAMTOP=106:REM 

2 PMBASE=54279:REM 

3 SDMCTL=559:REM 

4 GRACTL=53277 : REM 

5 HP0SP0=53248:REM 

6 PC0LR0=704:REM 

10 GRAPHICS 0:A=PEEK(RAMT0P)-16:REM 

20 POKE PMBASE,A 

30 MYPMBASE=256*A 

40 POKE SDMCTL,62 

50 POKE GRACTL,3 

60 POKE HPOSP0,102 

70 FOR l=MYPMBASE+1024 TO MYPMBASE+1280 
80 POKE l,0 
90 NEXT I 

100 POKE PC0LR0,140 
110 FOR 1=0 TO 15 
120 READ X 

130 POKE MYPMBASE+1 100+1 ,X 
140 NEXT I 

150 DATA 14,29,24,24,24,24,24,24 
160 DATA 24,24,24,24,24,24,184,112 
170 ?" ":REM 
180 POSITION 15,6 
190 ?"xdx" 



OS top of RAM pointer 

ANTIC player-missile RAM pointer 

shadow of DMACTL 

CTIA's graphics control register 
horizontal position register of P0 
shadow of player 0 color register 
must back up for 1-1 1 ne resolution 



clear screen 
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This program produces the following display: 



Figure 4.4 
using a player as a special character 

A particularly useful application of players Is for cursors. With 
their ability to smoothly move anywhere over the screen without disturbing 
Its contents they are Ideally suited for such applications. The cursor can 
change color as It moves over the screen to Indicate what It has under It. 

Player-mlssI le graphics provide many capabilities. Their uses for 
action games as animated objects are obvious. They have many serious uses 
as well. They can add color and resolution to any display. They can 
present special characters. They can be used as cursors. Use them. 



CHAPTER 5 
DISPLAY LIST INTERRUPTS 



The display list interrupt Is one of the most powerful capabilities 
built Into the ATARI Personal Computer System. It Is also one of the least 
accessible features of the system, requiring a firm understanding of assembly 
language as well as all of the other characteristics of the machine. Display 
list interrupts all by themselves provide no additional capabilities; they 
must be used In conjunction with the other features of the system such as 
player-missile graphics, character set indirection, or color register 
Indirection. With display list Interrupts the full power of these features 
can be deployed. 

Display list interrupts take advantage of the sequential nature of the 
raster scan television display. The television draws the screen image In a 
time sequence. It draws images from the top of the screen to the bottom. 
This drawing process takes about 13,000 microseconds, which looks 
Instantaneous to the human eye, but Is a long time In the time scale that the 
computer works In. The computer has plenty of time to change the parameters 
of the screen display while It Is being drawn. Of course, It must effect 
each change each time the screen Is drawn, which is 60 times per second. 
Also (and this Is the tricky part), It must change the parameter in question 
at exactly the same time each time the screen Is drawn. That Is, the cycle 
of changing screen parameters must be synchronized to the screen drawing 
cycle. One way to do this might be to lock the 6502 up Into a tight timing 
loop whose execution frequency is exactly 60 Hertz. This would make It very 
difficult to carry out any computations other than the screen display 
computations. It would also be a tedious job. A much better way would be to 
interrupt the 6502 just before the time has come to change the screen 
parameters. The 6502 responds to the Interrupt, changes the screen 
parameters, and returns to Its normal business. The Interrupt to do this 
must be precisely timed to occur at exactly the same time during the screen 
drawing process. This specially timed Interrupt Is provided by the ANTIC 
chip; It Is called a display list interrupt (DLI). 

The timing and execution of any interrupt process can be Intricate; 
therefore I shall first narrate the sequence of events In a properly working 
display list interrupt. The process begins when the ANTIC chip encounters a 
display list Instruction with Its interrupt bit (bit D7) set. ANTIC waits 
until the last scan line of . 1^ie ipode line it is currently displaying. ANTIC 
then refers to Its NMIEN >e^Ister^S see If display list Interrupts have been 
enabled. If the enable bit Is clear, ANTIC ignores the Interrupt and 
continues Its regular tasks. If the enable bit Is set, ANTIC pulls down the 
NMI line on the 6502. ANTIC then goes back to its normal display activities. 
The 6502 vectors through the NMI vector to an Interrupt service routine In 
the OS. This routine first determines the cause of the Interrupt. If the 
Interrupt Is Indeed a display list Interrupt, the routine vectors through 
addresses $0200, $0201 ( lo then hi) to a DLI service routine. The DLI 
routine changes one or more of the graphics registers which control the 
display. Then the 6502 RTIs to resume Its mainline program. 

„ 

-■■ 

There are a number of s+eps Involved In setting up a DLI. The very 
first thing you must do Is write the DLI routine Itself. The routine must 
push any 6502 registers that will be altered onto the stack, as the OS 
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Interrupt poll routine saves no registers, (The 6502 does automatically push 
the Processor Status Register onto the stack •) The routine should be short 
and fast; It should only change registers related to the display. It should 
end by restoring any 6502 registers pushed onto the stack. Next you must 
place the DLI service routine somewhere In memory. Page 6 is an ideal place. 
Set the vector at $0200, $0201 to point to your routine. Determine the 
vertical point on the screen where you want the DLI to occur, then go to the 
corresponding display list Instruction and set bit D7 of the previous 
Instruction. Finally, enable the DLI by setting bit D7 of the NMIEN register 
at $D40E. The DLI will Immediately begin functioning. 

As with any Interrupt service routine, timing considerations can be 
critical. ANTIC does not send the Interrupt to the 6502 Immediately upon 
encountering an Interrupt instruction; It delays this until the last scan 
line of the Interrupting mode line. The 6502 and the Interrupt service 
routine In the OS together consume between 18 and 25 machine cycles. Thus, 
the very first Instruction of your DLI service routine will not be reached 
until at least 18 machine cycles have elapsed In the last scan line of the 
interrupting mode line. 18 machine cycles correspond to 36 color clocks on 
the screen. Thus, your DLI service routine will begin executing while the 
electron beam Is partway across the screen In the last scan line of the 
Interrupting mode line. For example, if such a DLI routine changes a color 
register, the old color will be displayed on the left half of the screen and 
the new color will show up on the right half of the screen. Because of 
uncertain timing In the response of the 6502 to an Interrupt, the border 
between them will not be sharp but will jiggle back and forth irrltatlngly . 

There Is a solution to this problem. It Is provided In the form of the 
WSYNC (wait for horizontal sync) register. Whenever this register Is 
addressed In any way, the ANTIC chip pulls down the RDY line on the 6502. 
This effectively freezes the 6502 until the register Is reset by a horizontal 
sync. The effect is that the 6502 freezes until the electron beam returns to 
the left edge of the screen. If you Insert a STA WSYNC instruction just 
before the Instruction which stores a value Into a color register, the color 
will go In while the beam Is off the left edge of the screen. The color 
transition will occur one scan line lower, but will be neat and clean. 

The proper use of a DLI then Is to set the DLI bit on the mode line 
BEFORE the mode line for which you want the action to occur. The DLI service 
routine should first save the 6502 registers onto the stack, and then load 
the 6502 registers with the new graphics values to be used. It should 
execute a STA WSYNC, and then store the new values Into the appropriate ANTIC 
or CTIA registers. Finally, It should restore the 6502 registers and return 
from the Interrupt. This procedure will guarantee that the graphics 
registers are changed at the beginning of the desired line while the electron 
beam is off the screen. 
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A simple program demonstrating a DLI Is given below 



10 DL I ST=PEEK(560)+256*PEEK(561 ) :REM 
20 POKE DLIST+15,130:REM 
30 FOR l=0 TO 19:REM 
40 READ A: POKE 1 536+ I , A: NEXT I 
50 DATA 72,138,72,169,80,162,88 
60 DATA 141,10,212,141,23,208 
70 DATA 141,24,208,104,170,104,64 
80 POKE 512,0:POKE 513,6: 
90 POKE 54286, 192: REM 



find display I 1st 

Insert Interrupt Instruction 

loop for poking DLI service routine 



poke tn Interrupt vector 
enable DLI 



This routine uses the following assembly language DLI service routine: 



PHA 




save accumu I ator 


TXA 






PHA 




save X-reglster 


LDA 


#$50 


dark color for characters 


LDX 


#$58 


p I nk 


STA 


WSYNC 


wait 


STA 


C0LPF1 


store color 


STX C0LPF2 


store color 


PLA 






TAX 






PLA 
RTI 




restore registers 
done 



This Is a very simple DLI routine. It changes the background color 
from blue to pink. It also changes the color of the characters so that they 
show up as dark against the pink background. One might wonder why the upper 
half of the screen remains blue even though the DLI routine keeps stuffing 
pink Into the color register. The answer is that the OS vertical blank 
interrupt routine keeps stuffing blue Into the color register during the 
vertical blank period. The blue color comes from the OS shadow register for 
that color register. Every hardware color register Is shadowed out to a RAM 
location. You may already know about these shadow registers at locations 
708 through 712. For most purposes you can change colors by poking values 
Into the shadow registers. If you poke directly Into the hardware 
registers, the OS shadow process will wipe out your poked color within a 
60th of a second. For DLI f S, however, you must store your new color values 
directly Into the hardware registers. You can not use a DL I to set the 
color of the first displayed line of the screen; the OS takes care of that 
line for you. Use DLI f s to change colors of lines below the first line. 

By stuffing colors directly into the hardware registers you create a 
new problem: you defeat the automatic attract mode. Attract mode Is a 
feature provided by the operating system. After nine minutes without a 
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keypress, the colors on the screen begin to cycle through random hues at 
lowered luminances. This Insures that a computer left unattended for 
several hours does not burn an Image Into the television screen. It Is easy 
to build attract mode Into a display list Interrupt. Only two lines of 
assembly code need be Inserted Into the DLI routine: 



OLD 

LDA NEWCOL 
STA WSYNC 
STA C0LPF2 



NEW 

LDA NEWCOL 
EOR COLRSH r 
AND DRKMSK ifh 
STA WSYNC 
STA C0LPF2 



DRKMSK and COLRSH are zero page locations ($4E and $4F) set up and updated 
by the OS during vertical blank Interrupt. When attract mode Is not in 
force COLRSH takes a value of 00 and DRKMSK takes $FF. When attract mode Is 
in force, COLRSH is given a new random value every four seconds and DRKMSK 
holds a value of $F6. Thus, COLRSH scrambles the color and DRKMSK lops off 
the highest luminance bit. 

The implementation of attract mode In DLI's exacerbates an already 
difficult problem: the shortage of execution time during a DLI. A 
description of DLI timing will make the problem more obvious. DLI execution 
Is broken into three phases. Phase One covers the period from the beginning 
of the DLI to the STA WSYNC instruction. During Phase One the electron beam 
is drawing the last scan line of the Interrupting mode line. Phase Two 
covers the period from the STA WSYNC instruction to the appearance of the 
beam on the television screen. Phase Two corresponds to horizontal blank; 
all graphics changes should be made during Phase Two. Phase Three covers 
the period from the appearance of the beam on the screen to the end of the 
DLI service routine. The timing of Phase Three is not critical 

One horizontal scan line takes 114 clock cycles of real time. A DLI 
reaches the 6502 on or around cycle number 15. The 6502 takes about 7 
cycles to respond to the Interrupt. The OS routine to service the Interrupt 
and vector It on to the DLI service routine takes 11 machine cycles. Thus, 
the DLI service routine Is not reached until about 33 clock cycles have 
elapsed. Furthermore, the STA WSYNC Instruction must be begun by cycle 
number 103; this reduces the time available In Phase One by 11 cycles. 
Finally, ANTIC's DMA will steal some of the remaining clock cycles from the 
6502. Nine cycles will be lost to memory refresh DMA. This leaves an 
absolute maximum of 61 cycles available for Phase One. This maximum Is 
achieved only with blank line mode lines. Character and map mode 
instructions will result In the loss of one cycle for each byte of display 
data. The worst case arises with BASIC modes 0, 7, and 8, which require 40 
bytes per line. Only 21 machine cycles are available to Phase One In such 
modes. Thus, a Phase One routine will have from 21 to 61 machine cycles of 
execution time available to it. 
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Phase Two, the critical phase, extends over 24 clock cycles of real 
time. As with Phase One, some of these cycles are lost to cycle stealing 
DMA. PI ayer-ml ss I I e graphics will cost five cycles If they are used. The 
display Instruction will cost one cycle; If the LMS option Is used two more 
cycles will be stolen. Finally, one or two cycles may be lost to memory 
refresh or display data retrieval. Thus, from 14 to 23 machine cycles are 
available to Phase Two. 

The problems of DLI timing now become obvious. To load, attract and 
store a single color will consume 14 cycles. Saving A, X, and Y onto the 
stack and then loading, attracting, and saving 3 colors Into A, X, and Y 
will cost 47 cycles, most If not all of Phase One. Obviously, the 
programmer who wishes to use DLI's for extensive graphics changes will 
expend much effort on the timing of the DLI. Fortunately, the beginning 
programmer need not concern himself with extensive timing calculations. If 
only single color changes or simple graphics operations are to be performed, 
cycle counting and speed optimization are unnecessary. These considerations 
are only important for high-performance situations. 

There are no simple options for the programmer who needs to change more 
than three color registers In a single DLI. It might be possible to load, 
attract, and store a fourth color early In Phase Three if that color Is not 
displayed on the left edge of the screen. Similarly, a color not showing up 
on the right side of the screen could be changed during Phase One. Another 
approach is to break one overactive DLI Into two less ambitious DLI's, each 
doing half the work of the original. The second DLI could be provided by 
Inserting a single scan line blank Instruction (with DLI bit set) Into the 
display list just below the main Interrupting mode line. This will of 
course consume some screen space. 

Another partial solution Is to perform the attract chores during 
vertical blank periods. To do this, two tables of colors must be kept In 
RAM. The first table contains color values Intended to be displayed by the 
DLI routines. The second table contains the attracted values of these 
colors. During vertical blank, a usei — supplied interrupt service routine 
fetches each color from the first table, attracts It, and stores the 
attracted color to the second table. The DLI routine then retrieves values 
directly from the second table without paying the time penalty for attract. 

It Is often desirable to have a number of DLI's occurring at several 
vertical positions on the screen. This Is an important way to add color to 
a display. Unfortunately, there Is only one DLI vector; If multiple DLI's 
are to be Implemented then the vectoring to the appropriate DLI must be 
implemented in the DLI routine Itself. There are several ways to do this. 
If the DLI routine does the same process with different values then It can 
be table-driven. On each pass through the DLI routine a counter Is 
Incremented and used as an Index to a table of values. A sample DLI routine 
for doing this Is as follows: 
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The BASIC program to call this routine is: 



10 GRAPHICS 7 

20 DL I ST=PEEK(560)+256*PEEK(561 ) :REM 
30 FOR J =6 TO 84: REM 
40 POKE DLIST+J,141 :REM 
50 NEXT J 
60 FOR J=0 TO 30 

70 READ A .-POKE 1536+J,A:NEXTJ:REM 
80 DATA 72,138,72,238,32,6,175,32,6 
90 DATA 189,0,240,141,10,212,141,26,208 
100 DATA 224,79,208,5,169,0 
110 DATA 141,32,6,104,170,104,64 
120 POKE 51 2,0: POKE 51 3, 6: REM 
130 POKE 54286,1 92: REM 



find display 1 1st 

give every mode line a DL I 

BASIC mode 7 with DL I bit set 



poke In DLI service routine 



• 



vector to DLI service routine 
enable DLI 



<£0 \\*J0£ e>C colov- 




This program will put 80 different colors onto the screen. 

There are other ways to Implement multiple DLI's. One way Is to use a 
DLI counter as a test for branching through the DLI service routines to the 
proper DLI service routine. This slows down the response of all the DLMs, 
particularly the ones at the end of the test sequence. Another way Is to 
have each DLI service routine write the address of the next routine Into the 
DLI vector at $200, $201. This should be done during Phase Three. This Is 
the most general solution to the problem of multiple DLI's. It has the 
additional advantage that vectoring logic Is performed after the time 
critical portion of the DLI, not before. 

The OS keyboard click routine Interferes with the function of the DLI. 
Whenever a key Is pressed and acknowledged, the onboard speaker Is clicked. 
The timing for this click is provided by several STA WSYNC instructions. 



i 
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This can throw off the timing of a DLI routine and cause the screen colors 
to jump downward by one scan line for a fraction of a second. There Is no 
easy solution to this problem. One possible solution Involves the VCOUNT 
register, a read-only register In ANTIC which tells what scan line ANTIC Is 
displaying. A DLI routine could examine this register to decide when to 
change a color. Another solution Is to disable the OS keyboard service 
routine and provide your own keyboard routine. This would be a tedious job. 
The final solution Is to accept no inputs from the keyboard. If keypresses 
are not acknowledged, the screen jiggle does not occur. 

The DLI was designed to replace a more primitive software/hardware 
technique called a kernel. A kernel Is a 6502 program loop which Is 
precisely timed to the display cycle of the television set. By monitoring 
the VCOUNT register and consulting a table of screen changes catalogued as a 
function of VCOUNT values, the 6502 can arbitrarily control all graphics 
values for the entire screen. A high price Is paid for this power: the 6502 
is not available for computations during the screen display time, which is 
about 15% of the time. Furthermore, no computation may consume more than 
the 4000 or so machine cycles available during vertical blank and overscan 
periods. This restriction means that kernels can only be used with programs 
requiring little computation, such as certain skill and action games. For 
example, the BASKETBALL program for the ATARI 400/800™ uses a kernel; the 
program requires little computation but much color. The multi-colored 
players In this game could not be done with display list Interrupts, because 
DLMs are keyed to playfleld vertical positions, not player positions. 

It Is possible to extend the kernel Idea right Into a single scan line 
and change graphics registers on the fly. In this way a single color 
register can present several colors on a single scan line. The horizontal 
position of the color change Is determined by the amount of time that 
elapses before the change goes In. Thus, by carefully counting machine 
cycles the programmer can get more graphics onto the screen. Unfortunately, 
this Is extremely difficult to achieve In practice. With ANTIC DMA I ng the 
6502, It Is very difficult to know exactly how many cycles have really 
elapsed; a simple count of 6502 cycles Is not adequate. If ANTIC's DMA Is 
turned off, the 6502 can assume full control of the display but must then 
perform all the work that ANTIC normally does. For these reasons horizontal 
kernels are seldom worth the effort. However, If the two images to be 
displayed In different colors are widely separated, say by 20 color clocks 
or more, the separation should cover up the timing uncertainties and render 
this technique feasible. 

The tremendous value of graphics Indirection and all those modifiable 
registers In the hardware now becomes obvious. With display list 
Interrupts, every one of those registers can be changed on the fly. You can 
put lots of color, graphics, and special effects onto the screen. The most 
obvious application of DLI's Is to put more color onto the screen. Each 
color register can be changed as many times as you have DLI's. This applies 
to both playfleld color registers and player color registers. Thus, you 
have up to nine color registers, each of which can display up to 128 
different colors. Is that enough color for you? Of course, a normal 
program would not lend Itself to effectively using all of those colors. Too 
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many DLI's start slowing down the whole program. Sometimes the screen 
layout cannot accomodate lots of DLI's. In practice, a dozen colors Is 
easy, two dozen requires careful planning, and more than that requires a 
contrived situation. 

DLI's can give more than color; they can also be used to extend the 
power of p I ayer-mi ss 1 1 e graphics. The horizontal position of a player can 
be changed by a DLI. In this way a player can be repositioned partway down 
the screen. A single player can have several Incarnations on the screen. 
If you Imagine a player as a vertical column with Images drawn on It, a DLI 
becomes a pair of scissors with which you can snip the column and reposition 
sections of It on the screen. Of course, no two sections of the player can 
be on the same horizontal line, so two incarnations of the player cannot be 
on the same horizontal line. If your display needs allow graphics objects 
that will never be on the same horizontal line, a single player can do the 
job. 

Another way DLI's can be used In conjunction with players Is to change 
their width or priority. This would most often be used along with the 
priority masking trick described In Chapter 4. 

The last application of DLI's Is the changing of character sets partway 
down the screen. This allows a program to use character graphics in a large 
window and regular text In a text window. Multiple character set changes 
are possible; a program might use one graphics character set at the top of 
the screen, another graphics character set in the middle of the screen, and 
a regular text character set at the bottom. A 'Rosetta Stone' program would 
also be possible, showing different text fonts on the same screen. The 
vertical reflect bit can be changed with a DLI routine, allowing some text 
to be rights ide up and other text to be upside down. 

The proper use of the DLI requires careful layout of the screen 
display. The designer must give close consideration to the vertical 
architecture of her display. The raster scan television system Is not 
two-d Imens I ona I I y symmetric; It has far more vertical structure than 
horizontal structure. This Is because the pace for horizontal screen 
drawing Is about 200 times faster than the pace for vertical screen drawing. 
The ATARI 400/800™ display system was designed specifically for raster scan 
television, and It mirrors the anlsotropy of the raster scan system. The 
ATARI 400/800™ display Is not a flat, blank sheet of paper on which you 
draw; It is a stack of thin strips, each of which can take different 
parameters. The programmer who Insists on designing an isotropic display 
wastes many opportunities. You will achieve optimal results when you 
organize the Information you wish to display In a strong vertical 
structure. This allows the full power of the DLI to be brought to bear. 

Figure 5.1 shows some screen displays from various programs and gives 
estimates of the degree of vertical screen architecture used In each. 
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SPACE INVADERS 
(Trademark of Talto America Corporation) 

***LOTS*** 



SCRAM™ 

(A Nuclear Reactor Simulation) 
***LITTLE*** 




MISSILE COMMAND™ STAR RAIDERS 

***SOME*** ***L I TTLE*** 




GRAPH IT™ ASTEROIDS™ 
***NONE*** ***|\|ONE*** 



Figure 5.1 

examples of vertical screen architecture 
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CHAPTER 6 
SCROLLING 



Quite frequently the amount of information that a programmer wants to 
display exceeds the amount of information that can fit onto the screen. One 
way of solving this problem Is to scroll the information across the display. 
For example, listings of BASIC programs scroll vertically from the bottom to 
the top of the screen. All personal computers Implement this type of 
scrolling. However, the ATARI Personal Computer System has two additional 
scrolling facilities that offer exciting possibilities. The first is 'Load 
Memory Scan 1 (LMS) coarse scrolling; the second Is fine scrolling. 

Conventional computers use coarse scrolling; In this type of scrolling 
the pixels that hold the characters are fixed In position on the screen and 
text Is scrolled by moving bytes through the screen RAM. The resolution of 
the scrolling Is a single character pixel, which Is very coarse. The 
scrolling this produces is jerky and quite unpleasant. Furthermore, It Is 
achieved by moving up to a thousand bytes around In memory, a slow and clumsy 
task. In essence, the program must move data through the playfleld to 
scrol I . 

Some personal computers can produce a somewhat finer scroll by drawing 
Images in a higher resolution graphics mode and then scrolling these images. 
Although higher scrolling resolution Is achieved, more data must be moved to 
attain the scrolling and the program Is consequently slowed. The fundamental 
problem Is that the scrolling Is implemented by moving data through the 
screen area. 

There Is a better way to achieve coarse scrolling with the ATARI 
400/800 7 ": move the screen area over the data. The display list opcodes 
support a feature called Load Memory Scan. The LMS Instruction was first 
described In Chapter 2. The LMS instruction tells ANTIC where the screen 
memory Is. A normal display list will have one LMS Instruction at the 
beginning of the display list; the RAM area It points to provides the screen 
data for the entire screen In a linear sequence. By manipulating the operand 
bytes of the LMS Instruction, a primitive scroll can be implemented. In 
effect, this moves the playfleld window over the screen data. Thus, by 
manipulating just two address bytes, you can produce an effect Identical to 
moving the entire screen RAM. The following program does just that: 



1 0 DL I ST=PEEK( 560 )+256*PEEK( 561 ) : REM 

20 LMSL0W=DLIST+4:REM 

30 LMSH I GH=DL I ST+5 : REM 

40 FOR l=0 TO 255: REM 

50 POKE LMSH I GH, I 

60 FOR J=0 TO 255: REM 

70 POKE LMSL0W,J 

80 FOR Y*t TO 50: NEXT Y:REM 

90 NEXT J 

100 NEXT I 



This program sweeps the display over the entire address space of the 



find display list 
get low address of LMS operand 
get high address of LMS operand 
outer I oop 
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computer. The contents of the memory are all dumped onto the screen. The 
scroll Is a clumsy serial scroll combining horizontal scrolling with vertical 
scrolling. A pure vertical scroll can be achieved by adding or subtracting a 
fixed amount (the line length In bytes) to the LMS operand. The following 
program does that: 



10 GRAPHICS 0 

20 DLIST=PEEK(560)+256*PEEK(561 ) 

30 LMSL0W=DL I ST+4 

40 LMSH I GH=DL I ST+5 

50 SCREENLOW=0 

60 SCREENHIGH=0 

70 SCREENLOW=SCREENLOW+40:REM 

80 IF SCREENL0W<256 THEN GOTO 120: REM 

90 SCREENL0W=SCREENL0W-256:REM 

100 SCREENH I GH=SCREENH I GH+1 

110 IF SCREENH I GH=256 THEN END 

120 POKE LMSL0W,SCREENL0W 

130 POKE LMSH I GH, SCREENH I GH 

140 GOTO 70 



next I I ne 
overflow? 

yes, adjust pointer 
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A pure horizontal scroll Is not so simple to do as a pure vertical 
scroll. The problem Is that the screen RAM for a simple display list Is 
organized serially. The screen data bytes for the lines are strung In 
sequence, with the bytes for one line Immediately following the bytes for the 
previous line. We can horizontally scroll the lines by shifting all the 
bytes to the left; this Is done by decrementing the LMS operand. However, 
the leftmost byte on each line will then be scrolled Into the rightmost 
position In the next higher line. The first sample program Illustrated this 
problem. 

The solution Is to expand the screen data area and break It up into a 
series of independent horizontal line data areas. Figure 6.1 schematically 
Illustrates this Idea: 
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normal data arrangement 



arrangement for horizontal scroll 



Figure 6.1 
arranging screen RAM 
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On the left Is the normal arrangement. One-dimensional serial RAM is stacked 
In linear sequence to create the screen data area. On the right Is the 
arrangement we need for proper horizontal scrolling. The RAM is of course 
still one-dimensional and still serial, but now It Is used differently. The 
RAM for each horizontal line extends much further than the screen can show. 
This Is no accident; the whole point of scrolling Is to allow a program to 
display more Information than the screen can hold. We can't show all that 
extra Information if we don't allocate the RAM to hold It. With this 
arrangement we can implement true horizontal scrolling. We can move the 
screen window over the screen data without the undesirable vertical roll of 
the earlier approach. 

The first step In implementing pure horizontal scroll Is to determine 
the total horizontal line length and allocate RAM accordingly. Next, we must 
write a completely new display list with an LMS instruction on each mode 
line. The display list will of course be longer than usual, but there Is no 
reason why we cannot write such a display list. What values do we use for 
the LMS operands? It Is most convenient to use the address of the first byte 
of each horizontal screen data line, the points marked with x's on the 
diagram. There will be one such address for each mode line on the screen. 
Once the new display list is In place, ANTIC must be turned onto it and 
screen data must be written to populate the screen. To execute a scroll, 
each and every LMS operand in the display list must be Incremented for a 
rlghtward scroll or decremented for a leftward scroll. Program logic must 
insure that the Image does not scroll beyond the limits of the allocated RAM 
areas; otherwise, garbage displays will result. In setting up such logic, 
the programmer must remember that the LMS operand points to the first screen 
data byte In the displayed line. The maximum value of the LMS operand is 
equal to the address of the last byte In the long horizontal line minus the 
number of bytes in one displayed line. 

As this process Is rather intricate, let us work out an example. First, 
we must select our total horizontal line length. We shall use a horizontal 
line length of 256 bytes, as this will simplify address calculations. Each 
horizontal line will then require one page of RAM. Since we will use BASIC 
mode 2, there will be 12 mode lines on screen; thus, 12 pages or 3K of RAM 
will be required. For simplicity (and to guarantee that our screen RAM will 
be populated with nonzero data), we will use the bottom 3K of RAM. This area 
Is used by the OS and DOS and so should be full of Interesting data. To make 
matters more Interesting, we'll put the display list onto page 6 so that we 
can display the display list on the screen as we are scrolling. The Initial 
values of the LMS operands will thus be particularly easy to calculate; the 
low order bytes will all be zeros and the high order bytes will be (In order) 
0, 1, 2, etc. The following program performs all these operations and 
scrolls the screen horizontally: 
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10 REM first set up the display list 
20 POKE 1536,1 12:REM 
30 POKE 1537,1 12: REM 
40 POKE 1538,1 12:REM 
50 FOR 1=1 TO 12: REM 
60 POKE 1536+3*1,71 :REM 
70 POKE 1536+3*1+1 ,0: REM 
80 POKE 1536+3*1+2, I : REM 
90 NEXT I 

100 POKE 1575,65: REM 
110 POKE 1576,0: REM 
120 POKE 1577,6 

130 REM tell ANTIC where display list 
140 POKE 560,0 
150 POKE 561,6 

160 REM now scroll horizontally 
170 FOR l=0 TO 235: REM 

175 REM we use 235 not 255 because screen width Is 20 characters 

180 FOR J=1 TO 12:REM for each mode line 

190 POKE 1 536+3* J+1 , I :REM put In new LMS low byte 

200 NEXT J 
210 NEXT I 

220 GOTO 170: REM endless loop 

This program scrolls the data from right to left. When the end of a 

page Is reached It simply starts over at the beginning. The display list can 

be found on the sixth line down (it's on page six). It appears as a sequence 
of double quotation marks. 

The next step Is to mix vertical and horizontal scrolling to get 
diagonal scrolling. Horizontal scrolling Is achieved by adding 1 to or 
subtracting 1 from the LMS operand. Vertical scrolling Is achieved by adding 
the line length to or subtracting the line length from the LMS operand. 
Diagonal scrolling Is achieved by executing both operations. There are four 
possible diagonal scroll directions. If, for example, the line length Is 256 
bytes and we wish to scroll down and to the right, we must add 256+(-1)=255 
to each LMS operand In the display list. This Is a two-byte add; the BASIC 
program example given above avoids the difficulties of two-byte address 
manipulations but most programs will not be so contrived. For truly fast 
two-dimensional scrolling assembly language will be necessary. 

All sorts of weird arrangements are possible If we differentially 
manipulate the LMS bytes. Lines could scroll relative to each other, or hop 
over each other. Of course, some of this could be done with a conventional 
display but more data would have to be moved to do It. The real advantage of 
LMS scrolling Is Its speed. Instead of manipulating an entire screenful of 
data, many thousands of bytes In size, a program need only manipulate two or 
perhaps a few dozen bytes. 
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FINE SCROLLING ~ 

The second Important scrolling facility of the ATARI 400/800™ Is the 
fine scrolling capability. Fine scrolling Is the capability of scrolling a 
pixel In steps smaller than the pixel size. Coarse scrolls proceed In steps 
equal to one pixel dimension; fine scrolls proceed In steps of one scan line 
vertically and one color clock horizontally. Fine scrolling can only carry 
so far; to get full fine scrolling over long distances on the screen we must 
couple fine scrolling with coarse scrolling. (Throughout this chapter the 
term pixel refers to an entire character, not to the smaller dots which make 
up a character.) 

There are only two steps to Implement fine scrolling. First, we set the 
fine scroll enable bits In the display list Instruction bytes for the mode 
lines in which we want fine scrolling. (In most cases we want the entire 
screen to scroll so we set all the scroll enable bits In all the display list 
Instruction bytes.) Bit D5 of the display list instruction Is the vertical 
scroll enable bit; bit D4 of the display list Instruction Is the horizontal 
scroll enable bit. We then store the scrolling value we desire into the 
appropriate scrolling register. There are two scrolling registers, one for 
horizontal scrolling and one for vertical scrolling. The horizontal scroll 
register (HSCROL) Is at $D404; the vertical scroll register (VSCROL) Is at 
SD405. For horizontal scrolling, we store into HSCROL the number of color 
clocks by which we want the mode line scrolled. For vertical scrolling, we 
store into VSCROL the number of scan lines that we want the mode line 
scrolled. These scroll values will be applied to every line for which the 
respective fine scroll Is enabled. 

There are two complicating factors that we encounter when we use fine 
scrolling. Both arise from the fact that a partially scrolled display shows 
more information than a normal display. Consider for example what happens 
when we horizontally scroll a line by half a character to the left. There 
are 40 characters In the line. Half of the first character disappears off of 
the left edge of the screen. The 40th character scrolls to the left. What 
takes Its place? Half of a new character should scroll In to take the place 
of the now scrolled 40th character. This character would be the 41st 
character. But there are only 40 characters In a normal line; what happens? 
If we have implemented coarse scrolling then the 41st character suddenly 
appears on the screen after the first character disappears off of the left 
edge. This sudden appearance Is jerky and unsightly. The solution to this 
problem has already been built Into the hardware. There are three display 
options for line widths: the narrow playfield (128 color clocks wide), the 
normal playfield (160 color clocks wide) and the wide playfield (192 color 
clocks wide). These options are set by setting appropriate bits In the 
DMACTL register. When using horizontal fine scrolling, ANTIC automatically 
retrieves more data from RAM than It displays. For example, If DMACTL Is set 
for normal playfield, which In BASIC mode 0 has 40 bytes per line, then ANTIC 

will actually retrieve data at a rate appropriate to wide playfield 48 

bytes per line. This will throw lines off horizontally if It Is not taken 
Into account. The problem does not manifest Itself If the programmer has 
already organized screen RAM Into long horizontal lines as In Figure 6.1. 
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The corresponding problem for vertical scrolling can be handled In 
either of two ways. The sloppy way is to Ignore it. Then we will not get 
half-images at both ends of the display. Instead, the images at the bottom 
of the display will not scroll In properly; they will suddenly pop Into view. 
The proper way takes very little work. To get proper fine scrolling Into and 
out of the display region we must dedicate one mode line to act as a buffer. 
We do this by refraining from setting the vertical scroll bit In the display 
list Instruction of the last mode line of the vertically scrolled zone. The 
window will now scroll without the unpleasant jerk. The screen Image will be 
shortened by one mode line. An advantage of scrolling displays now becomes 
apparent. It Is quite possible to create screen images that have more than 
192 scan lines In the display. This could be disastrous with a static 
display, but with a scrolling display Images which are above or below the 
displayed region can always be scrolled Into view. 

Fine scrolling will only scroll so far. The vertical limit for fine 
scrolling Is 16 scan lines; the horizontal limit for fine scrolling Is 16 
color clocks. If we attempt to scroll beyond these limits, ANTIC simply 
ignores the higher bits of the scroll registers. To get full fine scrolling 
(In which the entire screen smoothly scrolls as far as we wish) we must 
couple fine scrolling with coarse scrolling. To do this we first fine scroll 
the image, keeping track of how far It has been scrolled. When the amount of 
fine scrolling equals the size of the pixel, we reset the fine scroll 
register to zero and execute a coarse scroll. Figure 6.2 illustrates the 
process: 




start fine fine 
pos it ion scrol I scrol I 

once twice 



f i ne 
scrol I 
thrice 



fine 
scrol I 

four 
times 



fine 
scrol I 

five 
times 



fine 
scrol I 

six 
times 



fine 
scrol I 
seven 
times 



reset 
to 

start 
pos it ion 



and 

coarse 
scro I I 



Figure 6.2 
linking fine scroll to coarse scroll 
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The following program illustrates simple fine scrolling^ 




1 HSCR0L=54276 

2 VSCR0L=54277 

10 GRAPHICS 0:LIST 

20 DLIST=PEEK(560)+256*PEEK(561) 

30 POKE DLIST+10,50:REM 

40 POKE DLIST+11,50:REM 

50 FOR Y=0 TO 7 

60 POKE VSCR0L,Y:REM 

70 GOSUB 200: REM 

80 NEXT Y 

90 FOR X=0 TO 3 

100 POKE HSCR0L,X:REM 

110 GOSUB 200: REM 

120 NEXT X 

130 GOTO 40 

200 FOR J=1 TO 200 

210 NEXT J: RETURN 



enable both scrol Is 

do It for two mode lines 



vertical scrol I 
del ay 



horizontal scrol I 
del ay 




1 



This program shows fine scrolling taking place at very slow speed. It 
demonstrates several problems that arise when using fine scrolling. First, 
the display lines below the scrolled window are shifted to the right. This 
Is due to ANTIC'S automatically retrieving 48 bytes per line Instead of 40. 
The problem arises only In unrealistic demonstration programs such as this 
one; In real scrolling applications the arrangement of the screen data (as 
shown in Figure 6.1) precludes this problem. The second, more serious 
problem arises when the scroll registers are modified while ANTIC Is In the 
middle of Its display process. This confuses ANTIC and causes the screen to 
jerk. The solution Is to change the scroll registers only during vertical 
blank periods. This can only be done with assembly language routines. Thus, 
fine scrolling normally requires the use of assembly language. 



APPLICATIONS 

The applications of full fine scrolling for graphics are numerous. The 
obvious application is for large maps which are created with character 
graphics. Using BASIC Graphics mode 2 I have created a very large map of 
Russia which contains about 10 screenfuls of image. The screen becomes a 
window to the map. The user can scroll about the entire map with a joystick. 
The system Is very memory efficient; the entire map program plus data plus 
display list and character set definitions requires a total of about 4K of 
RAM. 

There are many other applications of this technique. Any very large 
image that can be drawn with character graphics Is amenable to this system. 
(Scrolling does not require character graphics. Map graphics are less 
desirable for scrolling applications because of their large memory 
requirements.) Large electronic schematics could be presented In this way. 
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The joystick could be used both to scroll around the schematic and to 
Indicate particular components that the user wishes to address. Large 
blueprints or architectural diagrams could also be displayed with this 
technique. Any big Image that need not be seen In Its entirety can be 
presented with this system. 

Large blocks of text are also usable here, although it might not be 
practical to read contlnous blocks of text by scrolling the image. This 
system is more suited to presenting blocks of Independent text. One 
particularly exciting idea is to apply this system to menus. The program 
starts by presenting a welcome sign on the screen with signs Indicating 
submenus pointing to other regions of the larger image. 'This way to 
addition' could point up while 'this way to subtraction' might point down. 
The user scrolls around the menu with the joystick, perusing his options. 
When he wishes to make a choice, he places a cursor on the option and presses 
the red button. Although this system could not be applied to all programs, 
it could be of great value to certain types of programs. 

There are two 'blue sky' applications of fine scrolling which have not 
yet been fully explored. The first Is selective fine scrolling, In which 
different mode lines of the display have different scroll bits enabled. 
Normally we would want the entire screen to scroll, but It Is not necessary 
to do so. We could select one line for horizontal scrolling only, another 
line for vertical scrolling only, and so forth. The second blue sky feature 
Is the prospect of using display list interrupts to change the HSCROL or 
VSCROL registers on the fly. Changing VSCROL on the fly Is a tricky 
operation; It would probably confuse ANTIC and produce undesirable results. 
Changing HSCROL Is also tricky but might be easier. 
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CHAPTER VII 



ATARI BASIC OVERVIEW 



This chapter discusses the ATARI BASIC. The four main topics are: 



1. What is ATARI BASIC - a description of what is required to make 
BASIC run, and a discussion of its strengths and weaknesses. 



2. How ATARI BASIC Works - a detailed analysis of how programs are 
tokenized and executed. 



3. Improving Program Performance - a list of methods to increase 
the speed of a program and decrease its size. 



4 



Advanced Programming Techniques - a series of custom applications 
or "tricks" to meet various programming needs. 



ATARI BASIC 



What Is ATARI BASIC 



ATARI BASIC is like other BASICs in that it is an interpreted language. 
This means programs can be run when they are entered without intermediate 
stages of compilation and linking. The ATARI BASIC interpreter resides in 
an 8K ROM cartridge in the left slot of the computer. It encompasses 
addresses A000 through BFFF. BASIC stores the user's program in RAM and 
at least one 8K RAM board is required for this. 

To use ATARI BASIC effectively one must know its strengths and 
weaknesses. With this information programs can be written that make good 
use of the assets and features of ATARI BASIC. 

Strengths of ATARI BASIC: 

1. It supports the operating system graphics - simple graphics 
calls can be made to display information on the screen. 

2. It supports the hardware - such calls as SOUND, STICK and PADDLE 
are simple interfaces to the hardware of the computer. 

3. Simple assembly interface - the USR function allows easy user 
access to assembly language routines. 

4. ROM based interpreter - the BASIC interpreter is in ROM, which 
prevents accidental modification by the user program. 

5. DOS support - specialized calls such as NOTE and POINT (DOS 

2. OS) allow the user to randomly access a disk through the disk 
operating system. 

6. Peripheral support - any peripheral recognized by the operating 
system can be accessed from a BASIC program. 

Weaknesses of ATARI BASIC: 

1. No support of integers - all numbers are stored as six byte BCD 
floating point numbers. 

2. Slow math package - since all numbers are six bytes long, math 
operations become rather slow. 

3. No string arrays - only one-dimensional strings can be created. 
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How ATARI BASIC Works 

A brief overview of the workings of the BASIC interpreter is as follows: 

1. BASIC gets a line of input from the user and converts it into a 
tokenized form. 

2. It then puts this line into a token program. 

3. This program is then executed. 

The details of these operations are discussed in the following four sections. 

A. THE TOKENIZING PROCESS 

B. THE TOKEN FILE STRUCTURE 

C. THE PROGRAM EXECUTION PROCESS 

D. SYSTEM INTERACTION 
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A. THE TOKENIZING PROCESS 



In simple terms, the tokenization of a line of code in BASIC looks 
like this: 

1. BASIC gets a line of input 

2. It then checks for legal syntax 

3. During syntax checking it is tokenized 

4. The tokenized line is moved into the token program 

5. If the line is in immediate mode it is executed 

To better understand the tokenizing process some terms must first be 
defined. These are: 

Token - an 8 bit byte containing a particular interpretable code. 

Statement - a complete "sentence" of tokens that causes BASIC to perform 

some meaningful task. In LIST form, statements are separated 
by colons. 

Line - one or more statements preceeded either by a line number in 

the range of 0 to 32767, or an immediate mode line with no 
number. 

Command - the first executable token of a statement that tells BASIC to 

interpret the tokens that follow in a particular way. 

Variable - a token that is an indirect pointer to its actual value; thus 

the value can be changed without changing the token. 

Constant - a six byte BCD value preceeded by a special token. This value 

remains unchanged throughout program execution. 

Operator - any one of 46 tokens that in some way move or modify the 

values that follow them. 

Function - a token that when executed returns a value to the program. 
EOL - "End of Line", a character with the value 9B Hex. 



BASIC begins the tokenizing process by getting a line of input. This 
input will be obtained from one of the handlers of the operating system. 
Normally it is from the screen editor, however with the ENTER command, any 
device can be specified. The call BASIC issues is a GET RECORD command, 
and the data returned is ATASCII information terminated by an EOL. This 
data is stored by CIO into the BASIC input line buffer from 580 to 5FF 
Hex. 
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After the record is returned the syntax checking and tokenizing 
processes begin. First BASIC looks for a line number. If one is found it 
is converted into a two byte integer. If no line number is present it is 
assumed to be in immediate mode and the line number 8000 Hex is assigned 
to it. These will be the first two tokens of the tokenized line. This 
line is built in the token output buffer that is 256 byte long and resides 
at the end of the reserved operating system RAM. 

The next token is a dummy byte reserved for the byte count (or 
offset) from the start of this line to the start of the next line. 
Following that is another dummy byte for the count of the start of this 
line to the start of the next statement. These values will be set when 
tokenization is complete for the line and the statement respectively. The 
use of these values is discussed in the program execution process section. 

BASIC now looks for the command of the first statement of the input 
line. A check is made to determine if this is a valid command by scanning 
a list of legal commands in ROM. If a match is found then the next byte 
in the token line becomes the number of the entry in the ROM list that 
matched. If no match is found a syntax error token is assigned to that 
byte and BASIC stops tokenizing, copies the rest of the input buffer in 
ATASCII format to the token output buffer, and prints the error line. 

Assuming a good line, following the command can be one of seven 
items: a variable, a constant, an operator, a function, a double quote, 
another statement, or an EOL. BASIC tests if the next input character is 
numeric. If not then it compares that character and those following 
against the entries of the variable name table. If this is the first line 
of code entered in the program then no match will be found. The characters 
are then compared against the function and operator tables. If no match 
is found there then BASIC assumes that this is a new variable name. Since 
this is the first variable it will be assigned the first entry in the 
variable name table. The characters are copied out of the input buffer 
and stored into the name table with the most significant bit (MSB) set on 
the last byte of the name. Fight bytes are then reserved in the variable 
value table for this entry. (See the variable value table discussion in 
the token file structure section.) 

The token that ends up in the tokenized line is the variable number 
minus one, with the MSB set. Thus the token of the first variable entered 
would be 80 Hex, the second would be 81, and so on up to FF for a total of 
128 unique variable numbers. 

If a function is found, then its entry number in the operator function 
table is assigned to the token. Functions require certain sequences of 
parameters; these are contained in syntax tables, and if they are not 
matched then a syntax error will result. 

If an operator is found, then a token is given its table entry number. 
Operators can follow each other in a rather complex fashion (such as 
multiple parentheses) so the syntax checking of them is a bit complicated. 
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In the case of the double quotes, BASIC assumes that a character 
string is following and assigns a OF Hex to the output token and reserves 
a dummy byte for the string length. The characters are moved from the 
input buffer into the output buffer until the second set of quotes is 
found. The length byte is then set to the character count. 

If the next characters in the input buffer are numeric, BASIC will 
convert them into a six byte BCD constant. A OE Hex token will be put in 
the output buffer, followed by the six byte constant. 

When a colon is encountered, a 14 Hex token is inserted in the output 
buffer and the offset from the start of the line is stored in the dummy 
byte that was reserved for the count to the start of the next statement. 
At this point another dummy byte is reserved and the process goes back to 
get a command. 

When the EOL is found, a 16 Hex token is stored and the offset from 
the start of the line is put in the dummy byte for the line offset. At 
this point tokenization is complete and BASIC will move the token line 
into the token program. First it searches the program for that line 
number. If it is found it replaces the old line with the new one. If it 
is not found then the new line is inserted in the correct numerical 
sequence. In both cases, the data following the line will either be moved 
up or down in memory to allow for an expanding and contracting program 
size. 

BASIC now checks if the tokenized line is an immediate mode line. 
If so, that line is executed according to the methods described in the 
interpretive process, if not then BASIC goes back to get another line of 
input. 

If at any time during the tokenizing process the length of the token 
line exceeds 256 bytes, an error 14 message (line too long) is sent to the 
screen and BASIC will go back to get the next line of input. 

An example line of input and its token form looks like this (all 
token values are hexadecimal): 

10 LET X=1 : PRINT X 



OA 00 13 OF 06 80 2D 0E 40 01 00 00 00 00 14 13 20 80 22 



Line 10 



Line 
Offset 



A W a 



Let 



Statement 
Offset 



1 



Numeric 
Constant 




Statement 
Offset 



End 
Of 

Statement 
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COMMANDS 
HEX DEC 



OPERATORS 
HEX DEC 



FUNCTIONS 
HEX DEC 



00 


0 


REM 


01 


1 


DATA 


02 


2 


INPUT 


03 


3 


COLOR 


04 


4 


LIST 


05 


5 


ENTER 


06 


6 


LET 


07 


7 


IF 


08 


8 


FOR 


09 


9 


NEXT 


OA 


10 


GOTO 


OB 


11 


GO TO 


OC 


12 


GOSUB 


OD 


13 


TRAP 


OE 


14 


BYE 


OF 


15 


CONT 


10 


16 


COM 


11 


17 


CLOSE 


12 


18 


CLR 


13 


19 


DEG 


14 


20 


DIM 


15 


21 


END 


16 


22 


NEW 


17 


23 


OPEN 


18 


24 


LOAD 


19 


25 


SAVE 


1A 


26 


STATUS 


1B 


27 


NOTE 


1C 


28 


POINT 


1D 


29 


XIO 


1E 


30 


ON 


1F 


31 


POKE 


20 


32 


PRINT 


21 


33 


RAD 


22 


34 


READ 


23 


35 


RESTORE 


24 


36 


RETURN 


25 


37 


RUN 


26 


38 


STOP 


27 


39 


POP 


28 


40 


? 


29 


41 


GET 


2A 


42 


PUT 


2B 


43 


GRAPH I CS 


2C 


44 


PLOT 


2D 


45 


POSITION 


2E 


46 


DOS 


2F 


47 


DRAWTO 


30 


48 


SETCOLOR 


31 


49 


LOCATE 


32 


50 


SOUND 


33 


51 


LPRINT 


34 


52 


CSAVE 


35 


53 


CLOAD 


36 


54 


[IMPLIED LET] 


37 


55 


ERROR- [SYNTAX] 



OE 
OF 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 



14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 



INUM CONST! 

ISTR CONST! 
ii 

[NOT USED] 



9 

$ 



[STMT END] 



1A 26 
1B 27 



1C 
1D 
1E 



28 
29 
30 



1F 31 
20 32 



21 
22 
23 
24 
25 
26 



33 
34 
35 
36 
37 
38 



27 39 

28 40 



29 
2A 



41 
42 



2B 43 
2C 44 



2D 
2E 
2F 
30 
31 
32 
33 



45 
46 
47 
48 
49 
50 
51 



34 52 

35 53 

36 54 

37 55 

38 56 

39 57 
3A 58 



[LINE END] 
GOTO 
GOSUB 
TO 

STEP 
THEN 
# 

<= [NUMERICS] 
<> 

>= 

< 

> 

c 

+ 

/ 

NOT 

OR 

AND 

( 

) 

= Carithm assign] 
= [string assign] 

<= [STRINGS] 

<> 

>= 

< 

> 

+ [UNARY] 



3D 61 
3E 62 
3F 63 

40 64 

41 65 

42 66 

43 67 

44 68 

45 69 

46 70 

47 71 

48 72 

49 73 
4A 74 
4B 75 
4C 76 
4D 77 
4E 78 
4F 79 

50 80 

51 81 

52 82 

53 83 

54 84 



STR$ 

CHR$ 

USR 

ASC 

VAL 

LEN 

ADR 

ATN 

COS 

PEEK 

SIN 

RND 

FRE 

EXP 

LOG 

CLOG 

SQR 

SGN 

ABS 

INT 

PADDLE 
STICK 

PTRIG 
STRIG 



3B 
3C 



59 
60 



( 
( 
( 
( 
( 



STRING LEFT PAREN] 
>RRAY LEFT PAREN] 
:DIM ARRAY LEFT PAREN] 
>UN LEFT PAREN] 
:DIM STR LEFT PAREN] 
>RRAY COMMA] 
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B. THE TOKEN FILE STRUCTURE 



The token file contains two major segments: 1) a group of zero page 
pointers that point into the token file, and 2) the actual token file 
itself. The zero page pointers are 2-byte values that point to various 
sections of the token file. There are nine 2-byte pointers and they are 
in locations 80 to 91 Hex. Following is a list of the pointers and the 
sections of the token file they reference. 

POINTER (Hex) TOKEN FILE SECTION (Contiguous Blocks) 

LOMEM 80,81 Token output buffer - this is the buffer BASIC uses 

to tokenize one line of code. It is 256 bytes long. 
This buffer resides at the end of the operating 
system's allocated RAM. 

VNTP 82,83 Variable Name Table - a list of all the variable names 

that have been entered in the program. They are 
stored as ATASCII characters, each new name stored in 
the order it was entered. Three types of name entries 
exist : 

1. Scalar variables - MSB set on last character in name. 

2. String variables - last character is a "$ M with the 
.MSB set. 

3. Array variables - last character is a "(" with the 
MSB set. 



Variable Name Table dummy end - BASIC uses this 
pointer to indicate the end of the name table. This 
normally points to a dummy zero byte when there are 
less than 128 variables. When 128 variables are 
present, this points to the last byte of the last 
variable name. 

Variable Value Table - this table contains current 
information on each variable. For each variable in 
the name table, 8 bytes are reserved in the value 
table. The information for each variable type is: 



BYTE NUMBER 1 


2 


3 4 | 5 6 | 7 8 


SCALAR 00 


Var# 


Six byte BCD constant 


ARRAY (DIMed) 41 | 
(unDIMed) 40 


Var# 


Offset from 
STARP(8C,8D) 


r 

first 
DIM + 1 


I 

second 
DIM + 1 


STRING (DIMed) 81 ! 
(unDIMed) 80 


Var# 

I 


Offset from 
STARP(8C,8D) 


Length 

I 


DIM 



A scalar variable contains a numeric value. An example 
is X=1. The scalar is X and its value is 1, stored in 
six byte BCD format. An array is composed of numeric 
elements stored in the string/array area and has one 
entry in the value table. A string, composed of 
character elements in the string/array area, also has 
one entry in the table. 



VNTD 84,85 



VVTP 86,87 
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POINTER (Hex) 




STMTAB 88,89 



5TMCUR 8A,8B 



TOKEN FILE SECTION (Contiguous Blocks) 

The first byte of each value entry indicates the type 
of variable: 00 for a scalar, 40 for an array, and 80 
for a string. If the array or string has been dimen- 
sioned, then the LSB is set on the first byte. 

The second byte contains the variable number. The 
first variable entry is number zero and if 128 variables 
were present the last would be 7F. 

In the case of the scalar variable the third through 
eighth byte contain the six byte BCD number that has 
currently been assigned to it. 

For arrays and strings, the third and fourth bytes 
contain an offset from the start of the string/array 
area (described below) to the beginning of the data. 

The fifth and sixth bytes of an array contain its 
first dimension. The quantity is a two byte integer 
and its value is 1 greater than the user entered. The 
seventh and eighth bytes are the second dimension, 
also a value of 1 greater. 

The fifth and sixth bytes of a string are a two byte 
integer that contains its current length. The seventh 
and eighth bytes are its dimensions. 

Statement Table - this block of data includes all the 
lines of code that have been entered by the user and 
tokenized by BASIC, and it also includes the immediate 
mode line. The format of these lines is described in 
the tokenized line example of the section on the 
tokenizing process. 

Current Statement - this pointer is used by BASIC to 
reference particular tokens within a line of the 
statement table. When BASIC is waiting for input, 
this pointer is set to the beginning of the immediate 
mode line. 



STARP 8C,8D 




String/Array area - this block contains all the 

string and array data. String characters are stored 

as one byte ATASCII entries, so a string of 20 characters 

will require 20 bytes. Arrays are stored with 6 byte 

BCD numbers for each element. A 10 element array will 

require 60 bytes. 

This area is allocated and subsequently enlarged 
by each dimension statement encountered, the amount 
being equal to the size of a string dimension or six 
times the size of an array dimension. 
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TOKEN FILE SECTION (Contiguous Blocks) 



RUNSTK 8E,8F Run Time Stack - this software stack contains GOSUB 

and FOR/NEXT entries. The GOSUB entry consists of 
four bytes. The first is a 0 byte indicating GOSUB, 
followed by the two byte integer line number on which 
the call occured, followed by the offset into that 
line so the RETURN can come back and execute the next 
statement • 

The FOR/NEXT entry contains 16 bytes. The first is 
the limit the counter variable can reach. The second 
byte is the step or counter increment. Each of these 
quantities is in 6 byte BCD format. The thirteenth 
byte is the counter variable number with the MSB set, 
the fourteenth and fifteenth bytes are the line 
number, and the sixteenth is the line offset to the 
FOR statement. 

MEMTOP 90,91 Top of Application RAM - this is the end of the user 

program. Program expansion can occur from this point 
to the end of free RAM, which is defined by the start 
of the display list. The FRE function returns the 
amount of free RAM by subtracting MEMTOP from HIMEM 
(2E5,2E6). Note that the BASIC MEMTOP is not the same 
as the OS variable called MEMTOP. 
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C. THE PROGRAM EXECUTION PROCESS 

The process of executing a line of code involves reading the tokens 
that were created during the tokenization process. Each token has a 
particular meaning that causes BASIC to execute a specific series of 
operations. The method of doing this requires that BASIC get one token at 
a time from the token program and then process it. The token is an index 
into a jump table of routines, so a PRINT token will point indirectly to a 
PRINT processing routine. When that processing is complete, BASIC returns 
to get the next token. The pointer that is used to fetch each token is 
called STMCUR and is at 8A and 8B. 

The first line of code that is executed in a program is the immediate 
mode line. This is usually a RUN or GOTO. In the case of the RUN, BASIC 
gets the first line of tokens from the statement table (tokenized program) 
and processes it. If all the code is in-line, then BASIC will merely 
execute consecutive lines. 

If a GOTO is encountered, then the line to go to must be found. The 
statement table contains a partially linked list of line numbers and state- 
ments, the lowest line number first, followed by increasing line numbers 
up to the largest. If a line somewhere in the middle of the table is needed, 
the process is as follows: 

The address of the first line is found in the STMTAB pointer 
at 88 and 89. This is stored in a temporary pointer. The 
first two bytes of the first line are its line number. This 
number is compared against the requested line number. If the 
first number is less, then BASIC gets the next line by adding 
the third byte of the first line to the temporary pointer. 
The temporary pointer will be pointing to the second line. 
Again the first two bytes of this new line are compared to 
the requested line, and if they are less, the third byte is 
added to the pointer. If a line number does match, then the 
contents of the temporary pointer are moved into STMCUR and 
BASIC will fetch the next token from the new line. Should the 
requested line number not be found, then an Error 12 will be 
generated • 

The GOSUB involves more processing than the GOTO. The line finding 
routine is the same, but before BASIC goes to that line it sets up an 
entry in the Run Time Stack. It allocates four bytes at the end of the 
stack and stores a 0 in the first byte to indicate a GOSUB stack entry. 
It then stores the line number it was on when the call was made into the 
next two bytes of the stack. The final byte contains the offset in bytes 
from the start of that line to where the GOSUB token was found. BASIC 
then executes the line it looked up. When the RETURN is found, the entry 
on the stack is pulled off, and BASIC returns to the calling line. 

The FOR command causes BASIC to allocate 16 bytes on the Run Time 
Stack. The first six bytes are the limit the variable can reach in six 
byte BCD format. The second six bytes are the step, in the same format. 
Following these, BASIC stores the variable number (MSB set) of the counting 
variable. It then stores the present line number (2 bytes) and the offset 
into the line. The rest of the line is then executed. 



7-11 



ATARI BASIC 



When BASIC finds the NEXT command, it looks at the last entry on the 
stack. It makes sure the variable referenced by the NEXT is the same as 
the one on the stack and checks if the counter has reached or exceeded the 
limit. If not then BASIC returns to the line with the FOR statement and 
continues execution. If the limit was reached then the FOR entry is 
pulled off the stack and execution continues from that point. 

When an expression is evaluated, the operators are put onto an 
operator stack and are pulled off one at a time and evaluated. The order 
in which the operators are put onto the stack can either be implied, in 
which case BASIC looks up the operator's precedence from a ROM table, or 
the order can be explicitly stated by the placement of parentheses. 

If at any time the BREAK key is hit, the operating system sets a flag 
to indicate this occurrence. BASIC checks this flag after each token is 
processed. If it finds it has been set, it stores the line number at 
which this occured, prints out a "STOPPED AT LINE number" message, clears 
the BREAK flag and waits for user input. At this point the user could 
type CONT and program execution would continue at the next line. 
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D. SYSTEM INTERACTION 

BASIC communicates with the operating system primarily through the 
use of I/O calls to the Central I/O Utility (CIO). Following is a list of 
user BASIC calls and the corresponding operating system IOCBs. 

BASIC OS 



OPEN #1 ,12,0, "E:" I0CB=1 

Command=3 (OPEN) 
Aux1=12 (Input/Output) 
Aux2=0 

Buffer Address=ADR("E:") 

GET #1,X I0CB=1 

Command:: 7 (Get Characters) 
Buffer Length=0 

Character returned in accumulator 

PUT #1,X I0CB=1 

Command=11 (Put Characters) 
Buffer Length=0 

Character output through accumulator 
I0C8» 1 

Command=5 (Get Record) 

Buffer Length=Length of A$ (not over 120) 
Buffer Address=Input Line Buffer 

I0CB=1 

BASIC uses a special put byte vector 
in the IOCB to talk directly to the 
handler . 

XIO 18,#6,12,0,"S:" I0CB=6 

Command=18 (Special - Fill) 

Aux1=12 

Aux2=0 

SAVE/LOAD: When a BASIC token program is SAVEd to a device, two 
blocks of information are written. The first block consists of seven of 
the nine zero page pointers that BASIC uses to maintain the token file. 
These are L0MEM(80,81) through STARP (8C,8D). There is one change made to 
these pointers when they are written out: The value of LOMEM is subtracted 
from each of the two-byte pointers, and these new values are written to 
the device. Thus the first two bytes written will be 0,0. 

The second block of information written consists of the following 
token file sections: 1) The variable name table, 2) the variable value 
table, 3) the token program, and A) the immediate mode line. 

When this program is LOADed into memory, BASIC looks at the OS 
variable MEMLO (2E7,2E8) and adds its value to each of the two-byte zero 
page pointers as they are read from the device. These pointers are placed 
back on page zero and then the values of RUNSTK (8E,8F) and MEMTOP (90,91) 
are set to the value in STARP. 



INPUT #1,A$ 



PRINT #1,A$ 
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Next, 256 bytes are reserved in memory above the value of MEMLO to 
allocate space for the token output buffer. Then the token file informa- 
tion, consisting of the variable name table through the immediate mode 
line, is read in. This data is placed in memory immediately following the 
token output buffer. 



OS 



BASIC 



RAM 



MEMLO 2E7,2E8 



APPMHI 0E,0F 



MEMTOP 2E5,2E6 
SDLST 230,231 



SAVMSC 58,59 



PAGE 
SIX 



BASIC 
TOKEN 
PROGRAM 



FREE 
RAM 



DISPLAY 
LIST 



80,81 
82,83 
84,85 
86,87 
88,89 
8A,8B 
8C,8D 
8E,8F 
90,91 



0E,0F 



LOMEM 

VNTP 

VNTD 

VVTP 

STMTAB 

STMCUR 

STARP 

RUNSTK 

MEMTOP 

APHM 

4 

I 

FRE (0) 
I 



2E5,2E6 



HIMEM 



SCREEN 
RAM 



TXTMSC 294,295 



RAMTOP 6A 
RAMSIZ 2E4 



TEXT 
WINDOW 



OS AND BASIC POINTERS (NO DOS PRESENT) 
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Improving Program Performance 



Program performance can be improved in two ways. First the execution 
time can be decreased (it will run faster) and second, the amount of space 
required can be decreased, allowing it to use less RAM. To attain these 
two goals, the following lists can be used as guidelines. The methods of 
improvement in each list are primarily arranged in order of decreasing 
effectiveness. Therefore the method at the top of a list will have more 
impact than one on the bottom. 

Speeding Up A BASIC Program: 

1. Recode - since BASIC is not a structured language, the code 
written in it tends to be inefficient. After many revisions 
it becomes even worse. Thus, spending the time to restructure 
the code is worthwhile. 

2. Check algorithm logic - make sure that the code to execute a 
process is as efficient as possible. 

3. Put frequently called subroutines and FOR/NEXT loops at the 
start of the program - BASIC starts at the beginning of a 
program to look for a line number, so any line references near 
the end will take longer to reach. 

4. For frequently called operations within a loop^ use in-line code 
rather than subroutines - the program speed can be improved here 
since BASIC spends time adding and removing entries from the run 
time stack. 



5. Make the most frequently changing loop of a nested set the 
deepest - in this way the run time stack will be altered the 
fewest number of times. 

6. Simplify floating point calculations within the loop - if a 
result is obtained by multiplying a constant by a counter, time 
could be saved by changing the operation to an add of a constant. 

7. Set up loops as multiple statements on one line - in this way 
the BASIC interpreter will not have to get the next line to 
continue the loop. 

8. Disable the screen display - if visual information is not 
important for a period of time, up to a 30% time savings can be 
made with a POKE 559,0. 

9. Use a faster graphics mode or a short display list - if a full 
screen display is not necessary then up to 25% time savings can 
be made . 

10. Use assembly code - time savings can be made by encoding loops 
in assembler and using the USR function. 
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Saving Space In A BASIC Program: 

1) Recode - as mentioned previously, restructuring the program will 
make it more efficient. It will also save space. 

2) Remove remarks - remarks are stored as ATASCII data and merely 
take up space in the running program. 

3) Replace a constant used three times or more with a variable - 
BASIC allocates seven bytes for a constant but only one for a 
variable reference, so six bytes can be saved each time a 
constant is replaced with a variable assigned to that constant's 
value. 

4) Initialize variables with a read statement - a data statement 
is stored in ATASCII code, one byte per character, whereas an 
assignment statement requires seven bytes for one constant. 

5) Try to convert numbers used once and twice to operations of 
predefined variables - an example is to define Z1 to equal 1 , Z2 
to equal 2, and if the number 3 is required, replace it with the 
expression Z1 + Z2. 

6) Set frequently used line numbers (in GOSUB and GOTO) to predefined 
variables - if the line 100 is referenced 50 times, approximately 
300 bytes can be saved by equating Z100 to 100 and referencing 
Z100. 

7) Keep the number of variables to a minimum - each new variable 
entry requires 8 more bytes in the variable value table plus a 
few bytes for its name. 

8) Clean up the value and name tables - variable entries are not 
deleted from the value and name tables even after all references 
to them are removed from the program. To delete the entries 
LIST the program to disk or cassette, type NEW, then ENTER the 
program . 

9) Keep variable names as short as possible - each variable name is 
stored in the name table as ATASCII information. The shorter 
the names, the shorter the table. 

10) Replace text used repeatedly with strings - on screens with a 
lot of text, space can be saved by assigning a string to a 
commonly used set of characters. 

11) Initialize strings with assignment statements - an assignment of 
a string with data in quotes requires less space than a READ 
statement and a CHR$ function. 

12) Concatenate lines into multiple statements - three bytes can be 
saved each time two lines are converted into two statements on 
one line. 
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13) Replace once used subroutines with in-line code - the G05UB and 
RETURN statements waste bytes if used only once. 

14) Replace numeric arrays with strings if the data values do not 
exceed 255 - numeric array entries require six bytes each, 
whereas string elements only need one. 

15) Replace set color statements with POKE commands - this will save 
8 bytes. 

16) Use cursor control characters rather than POSITION statements - 
the POSITION statement requires 15 bytes for the X,Y parameters 
whereas the cursor editing characters are one byte each. 

17) Delete lines of code via program control - see the advanced 
programming techniques section. 

18) Modify the string/array pointer to load predefined data - see 
the advanced programming techniques section. 

19) Small assembly routines can be stored in remark statements - 
remarks are stored as unchanged ATASCII data. 

20) Chain programs - an example would be an initialization routine 
that is run first, and which then loads and runs the main 
program . 
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Advanced Programming Techniques 

When the fundamentals of ATARI BASIC are understood some interesting 
applications can be written. These can be strictly BASIC operations, or 
they can also involve features of the operating system. 

Example 1 - String Initialization - This program will set all the bytes of 
a string of any length to the same value. BASIC copies the first byte of 
the source string into the first byte of the destination string, then the 
second, third, and so on. By making the destination string the second 
byte of the source, the same character can be stored into the entire 
string. 

Example 2 - Delete Lines Of Code - By using a feature of the operating 
system, a program can delete or modify lines of code within itself. The 
screen editor can be set to accept data from the screen without user input. 
Thus by first setting up the screen, positioning the cursor to the top, and 
then stopping the program, BASIC will be getting the commands that have 
been printed on the screen. 

Example 3 - Saving The String/Array Area - If an array or string is always 
initialized to the same size and data, then an appreciable amount of 
program space can be saved by storing the information during the SAVE and 
deleting the initialization code for the next run. 

Example 4 - Save BCD Numbers To Disk - Whenever numeric data is written to 
a device it is sent as ATASCII information. This means the number 10 is 
written as an ATASCII 1 followed by a 0. This makes a mess out of fixed 
length records. One way to correct this is to store the six byte BCD 
number to disk directly by equating it to a string, and then writing that 
string. It can be retrieved in the same way. 

Example 5 - Player/Missile Graphics With Strings - A fast way to move 
player/missile graphics data is shown in this example. A dimensioned 
string has its string/array area offset value changed to point to the P/M 
graphics area. Writing to this string with an assignment statement will 
now write data into the P/M area at assembly language rates. 
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10 REM STRING INITIALIZATION 
20 DIM A$(1000) 
30 A$(1 )="A":A$(1000)="A" 
40 A$(2)=A$ 



10 REM DELETE LINE EXAMPLE 

20 GRAPHICS OrPOSITION 2,4 

30 ? 70:? 80:? 90:? "CONT" 

40 POSITION 2,0 

50 POKE 842, 13: STOP 

60 POKE 842,12 

70 REM THESE LINES 

80 REM WILL BE 

90 REM DELETED 



10 REM STRING/ ARRAY SAVE 

15 REM GOTO 20 FOR FIRST RUN 

17 REM DELETE LINE 20 FOR SECOND RUN 

18 GOTO 100 

20 DIM A$(10):A$="WWWWWWWWWW" 
30 STARP=PEEK(140)+PEEK(141 )*256 
40 STARP=STARP+10 

50 HI-INTC STARP/256 ) : LO=STARP-H I *256 

60 POKE 140,LO:POKE 141 ,H I 

70 SAVE "D: STRING": STOP 

100 STARP=PEEK(140)+PEEK(141 )*256 

110 STARP=STARP-10 

1 20 H I = I NT( STARP/256 ) : L0=STARP-H I *256 
130 POKE 140,LO:POKE 142,L0:P0KE 144, LO 
140 POKE 141,HI:P0KE 143,HI:P0KE 145, HI 
150 DIM A$(10) 
160 A$(10,10)="W" 
170 STOP 
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10 REM SAVE AND RETRIEVE BCD NUMBERS ON DISK 

15 DIM A(0),B$(6) 

20 B$(6,6)=CHR$(32) 

30 VTAB=PEEK(134)+PEEK(135)*256 

40 POKE VTAB+10,0 

50 OPEN #1,8,0,"D:TEST" 

60 FOR C=1 TO 15:A(0)=C:? #1;A$:NEXT C 

70 CLOSE #1 

80 OPEN #1,4,0,"D:TEST" 

90 FOR C=1 TO 15: INPUT #1,A$:? A(0):NEXT C 
100 CLOSE #1:END 



100 REM PLAYER/MISSILE EXAMPLE 
110 DIM A$(512),B$(20) 

120 X=X+1:READ A: IF A<>-1 THEN B$(X,X)=CHR$(A) :GOTO 120 

130 DATA 0,255,129,129,129,129,129,129,129,129,255,0,-1 

2000 POKE 559,62:POKE 704,88 

2020 l=PEEK(106)-16:P0KE 54279,1 

2030 POKE 53277, 3: POKE 710,224 

2040 VTAB=PEEK (134) +PEEK ( 1 35 ) *256 

2050 ATAB=PEEK(140)+PEEK(141 )*256 

2060 OFFS=I*256+1024-ATAB 

2070 H I = I NT( 0FFS/256 ) : LO=OFFS-H I *256 

2090 POKE VTAB+2,L0:P0KE VTAB+3,HI 

3000 Y=60:Z=100:V=1 :H=1 

4000 A$(Y,Y+11 )=B$:POKE 53248, Z 

4010 Y=Y+V:Z=Z+H 

4020 IF Y>213 OR Y<33 THEN V=-V 

4030 IF Z>206 OR Z<49 THEN H=-H 

4420 GOTO 4000 
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CHAPTER 8 
OPERATING SYSTEM 



INTRODUCTION TO THE 
OPERATING SYSTEM 



This section is a simple Introduction to the Operating System (O.S.) of 
the ATARI 400/800. This section also contains a brief description of the 
elements of the O.S. The following sections will describe these elements in 
detal I : 

Input/Output Subsystem 
ROM-Based Character Set 
System Routine's Vectors 
I nterrupt Hand I ers 
Mon i tor 

System Database 

System and Event Timers 

Floating Point Package 



The O.S. allows the application programmer access to the full 
capabilities of the computer's hardware. The ATARI Personal Computer 
System's hardware is capable of providing you with some excellent I/O 
functions via the I/O subsystem. The I/O subsystem Is a set of system 
routines that Interface with the I/O hardware. The rest of the O.S. supports 
the I/O subsystem and provides you with additional features you can use for 
app I Icat ions . 

The ROM-based character set is used by the display handlers to write 
characters on the television screen. If you wish, you can create your own 
character set and tell the O.S. to use It instead. 

The system vectors provide the glue that holds the O.S. together. The 
O.S. uses the vectors to move from one execution environment (BASIC, DUP, 
Star Raiders 1 ") to another. You can call any system routine by jumping to its 
vector. The vectors are most frequently used to call I/O system routines, 
set timers and transfer control to different execution environments. 

The system routines may be vectored in one of two ways. The ROM vectors 
are locations that contain JMP instructions to system routines and cannot be 
altered. The RAM vectors are locations that contain alterable addresses of 
system routines. The locations of both types of vectors are guaranteed to 
remain the same in future releases of the O.S. 

The computer generates interrupts for several different reasons. Some 
of the most common interrupts are keyboard, <BREAK>, serial bus, and vertical 
b I ank . 
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The O.S. monitor is a system routine to initialize the computer on 
power-up and system reset • The monitor Initializes the I/O subsystem, sets 
up the vectors and selects the execution environment after initialization is 
complete. 

The O.S. Is supported by a large database consisting of various system 
flags, I/O buffers, and screen/graphics registers. Most of the database Is 
dedicated to the I/O subsystem. The database also contains locations used by 
the other parts of the O.S. Application programmers can take advantage of 
the database to add features to their programs. 

The O.S. has two types of timers, system timers and hardware timers. 
System timers are used by applications programs as general purpose software 
timers. Hardware timers are used to time 'real time' events such as the 
television scan lines In a screen display. 

The floating point package Is a set of mathematical routines available 
to the user. The routines use binary coded decimal (BCD) arithmetic. 
Routines are provided to do the standard arithmetic functions (+,-,*,/) as 
well as conversion from ATASCI I to BCD and BCD to ATASCI I . You can find a 
description of the floating point package as well as how to use it In Section 
8 of the O.S. User Manual. Appendix 5 of this book contains an example using 
the package. 
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OPERATING SYSTEM 
I/O SUBSYSTEM STRUCTURE 



>LL PERIPHERAI S 
iXCEPT RESIDENT 
ISK HANDLER 



CIO CALL: 



CALL TO DEVICE USE HANDLER ADDRESS 



HANDLER: 



SERIAL BUS 
PERIPHERALS ONLY 




RESIDENT 
DISK HANDLER 



JSER PROGRAM 



(DOS or 

ASSEMBLER) 



DISK HANDLER CALL 
JSR DSKIOV 

BMI ERROR 

BPL SUUCESS 

4 



SERIAL 
I/O ROUTINE 
CSIO) 

zx 



r s 


RESIDENT 




DISK HANDLER 



sz 

SERIAL DATA 
TRANSFER VIA 

SERIAL BUS 



FIGURE 8.1 I/O SUBSYSTEM 



OPERATING SYSTEM 
SECTION 8.2 - - I/O SUBSYSTEM 



INTRODUCTION 

The I/O subsystem provides a convenient method of accessing the I/O 
hardware registers used by ANTIC, POKEY, CTIA and PI A. These special purpose 
chips control the I/O devices such as the keyboard, printer and disk. You 
simply pass control data to the I/O subsystem and it will perform the 
requested I/O function for that device. 

The I/O subsystem has two types of elements: I/O system routines and 
I/O system control blocks. The I/O system routines are the central I/O 
routine (CIO), the device handlers (i.e. E:, P:, K:) and the serial I/O 
routine (SIO). The system I/O control blocks contain control data that Is 
routed to the I/O subsystem. The user interface appears the same for all 
devices (e.g. the commands to output a line to the printer (P:) or to the 
display editor (E:) are very similar). 

You need to understand the structure of the I/O subsystem to get the 
most out of it. Figure 8.1 shows the relationship of the I/O system 
routines and the I/O system control blocks. 



I/O SYSTEM CONTROL BLOCKS 
There are three types of control blocks: 



Input/Output Control Block (IOCS) 
Zero-Page I/O Control Block (ZIOCB) 
Device Control Block (DCB) 

The I/O system control blocks are used to communicate Information about the 
I/O function to be executed. The control blocks provide the I/O system 
routines with control Information to perform the I/O function. The O.S. 
Manual has Information as to the detailed structure of the three types of 
control blocks In Section 5. 
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DCB CHART 



FUNCTION 


1 NAME 


LOCAT ION 


I RF AD 
810 


815 


DISK 

WR T TP 
nn 1 1 L 

810 


810/815 

DLL I Ur\ 

815 


PI IT 


I r UKMA I 


i PRINTER 820 

un t Tr 

WRITE 


Cpri al Ri ic T P> 
I JClldl DUS i.U. 


1 nnrvir 

I UULV1L 


1 r tmnn 1 
1 L3>U.>UUJ 


1 $30 


1 $30 


1 $30 


$30 


$30 


I $30 


I $40 


1 Device Number 


DUN IT 


1 [$0301] 


1 1-4 


1 1-8 


1 1-4 


1-8 


1-4 


1-4 


I 1 


i Command Byte 


1 DCOMND 


I [$0302] 


I $52 


I $52 


I $57 


$57 


$50 


I $21 


I $57 


Status 


1 DSTATS 


I [$0303] 


I $40 


I $40 


I $80 


$80 


$80 


I $40 


I $80 


Buffer Address 


1 DBUFLO 


[$0304] 


I U 


I U 


I U 


U 


U 


I u 


I U 




1 DVBUFHI 


I [$0305] 


I u 


I U 


I U 


U 


U 


u 


U 


Device Timeout 


1 DTIMLO 


I [$0306] 


I $30 


$30 


I $30 


$30 


$31 


I $130 


I 5 


Buffer Length 


DBYTLO 


[$0308] 


$80 


I 00 


I $80 


00 


$80/00 




I $40 




1 DBYTHI 


I [$0309] 


$00 


I 01 


I $00 


01 


$00/01 




I $00 




1 DAUX1 


I [$030A] 


I 2* 


I 2* 


I 2* 


2* 


- 2* 




I 1* 




I DAUX2 


I [$030B] 


I 2* 


I 2* 


I 2* 


2* I 


- 2* 




I 1* 



FIGURE 8.3 

1* = This byte determines printer mode (see 820 manual. 

2* = DAUX1 + DAUX2 specify sector for READ, WRITE (PUT), or WRITE verify. 
U = Indicates user-set address 
r indicates ignored. 



I0CB CHART 



CALL 




I ICHID I 


ICDN0 


I ICC0M | 


ICSTA I 


ICBAL 


I ICBAH | 


ICPTL 


I ICPTH 


I ICBLL 


I ICBLH 


I ICAX1 I ICAX2 


OPEN FILE- 


READ 


I x 




X 


I 3 




r»~te 1 I 


$80 


I 06 


X 




I x 


I x 


I X 


I 4 


I o 


OPEN FILE- 


WRITE 


I X 




X 


I 3 




N 


$80 


I 06 


X 




I X 


I x 


I x 


8 


I note 2 


GET BYTES 




X 




X 


I 7 




It 


00 


I 06 


X 




I X 


I $80 


I 00 


X 


I x 


PUT BYTES 




I x 




X 


I $B 




N 


00 


I 06 


X 




I X 


I $80 


I 00 


X 


I X 


GET RECORD 




I x 




X 


I 5 




II 


00 


I 06 


X 




I x 


I $80 


I 00 


X 


X 


PUT RECORD 




X 




X 


I 9 




II 


00 


I 06 


X 




X 


I $80 


I 00 


X 


I X 


CLOSE FILE 




X 




X 


I $C 




II 


X 


I X 


X 




I X 


I x 


I x 


X 


I x 


STATUS 




I x 




X 


I $D 




II 


X 


I X 


X 




I x 


I x 


I X 


X 


I x 
















FIGURE 8 


.2 
















NOTE 1 


= The 


status 


of the 1/0 


command is 


stored 


here 


and in the 


Y 


REG. 


on return from 


CIO. 






NOTE 2 


= The 


Auxila 


ry bytes of 


the IOCB's 


are used by 


some handl 


ers 


to 


indicate 


special 


modes. 






X 


= Indi 


cates 


ignore 


but 


do not 


chan 


ge the 


curren 


t value. 
















GENERAL 


NOTE: 


The 


above 


I0CB 


def ini 


tions 


assume 


• 
• 






















*=$600 
































I0BUFF 


.RES 




80 






USER 


1/0 


BUFFER 














FILE 




.BYTE 




'D:MYPR0G.BAS ' 


USER 


FILENAME 
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OPERATING SYSTEM - I/O SUBSYSTEM 



The eight lOCBs in the O.S. are used for communication between user 
programs and CIO. Figure 8.2 shows the content of an IOCB for some common 
I/O functions. The iOCB's are: 



Location, 


Name 


Length 


IOCB0 


"$340,16] 


I0CB1 


I$350,16] 


I0CB2 


I $360, 16] 


I0CB3 


I $370, 16] 


I 0CB4 | 


I $380, 16] 


I0CB4 


"$390,161 


I0CB5 


:$3A0,16l 


I0CB6 


"$3B0,16" 


I0CB7 


]$3C0,16l 



The second type of control block, the ZI0CB [$0020,16], is used to 
communicate I/O control data between CIO and the device handlers. When 
called, CIO uses the value contained in the X register as an index that 
points to the starting address of the IOCB (one of 8) to be used. CIO then 
moves the control data from the selected IOCB to the ZI0CB for use by the 
appropriate device handler. The ZI0CB Is of little interest unless you are 
writing a new device handler or are replacing a current one. See section 9 
of the O.S. User Manual for more information on the ZIOCB. . . f 

~\)C\j{lc CovaIyzJ 8>J 

The device handlers load control information into the DCB [$0300,16]. 
SIO will use the DCB Information and return the status information In the DCB 
for subsequent use by the device handler. Only device handlers that use the 
serial bus use the DCB and SIO. Section 9 of the O.S. User Manual contains a 
detailed description of the DCB. Figure 8.3 Illustrates some common I/O 
functions and the contents of their associated DCBs. 

The resident disk handler does not conform to the regular user-CIO- 
handler-SIO calling sequence. Instead, you use the DCB to communicate 
directly with the resident disk handler. Chapter 9 of this book contains 
more information on the resident disk handler. 
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I/O SUBSYSTEM 



CENTRAL I/O SYSTEM ROUTINE - CIO 



ClO's main function Is to route I/O control data to the correct device 
handler and then pass control to the handler. CIO also acts as a common exit 
routine for all of the device handlers. CIO is the common entry point for 
most of the O.S. I/O functions. For example, BASIC will call CIO while 
executing an OPEN statement. CIO supports the following functions: 



OPEN 
CLOSE 
GET CHARS 
READ RECORD 
PUT CHARS 
WRITE RECORD 
STATUS 
SPECIAL 



Devlce/f I le open 

Devlce/f I le close 

Read 1-N characters 

Read next record 

Write 1-N characters 

Write next record 

Get device status 

Device handler specific (e.g 



NOTE for FMS) 



You may wish to make your own CIO calls. The calling sequence for CIO is: 



;rem user has set up JOCB 
LDX #IOCBNUM ;set the IOCB index ( I0CB * 16) 

JSR CIOV ;system routine vector to CIO 

BMI ERROR ;ff branch taken then CIO returned 

; error code in Y register 

As shown In the above call, one of the lOCBs is used to communicate 
control data to CIO. You may use any one of the 8 lOCBs. CIO expects the 
IOCB index to be in the X register. On return, the status bits of the 6502 
are set to indicate success or error In the I/O operation. If the N bit Is 
clear (B f 0 f ) the I/O was done successfully, and the Y register will contain a 
1. If the N bit is set (BM ! ), the I/O request resulted in an error; the Y 
register will contain the error code. The error/success value Is also 
returned in the IOCB byte ICSTA (see IOCB definition). Chapter 5 of the O.S. 
User Manual has a sample program segment that calls CIO to OPEN a disk file, 
READ some records, and CLOSE the file. 



CIO routes I/O control data by using the IOCB index In the X register to 
move the contents of the your IOCB to the ZIOCB. CIO then calculates the 
device handler entry point and vectors to the appropriate device handler 
routine. Appendix VI is a flowchart of the CIO system routine. 

CIO calculates the device handler entry point in an indirect manner. 
During an OPEN call, CIO gets the device specification for the file to be 
OPENed . Let us assume that the device we want to OPEN Is the printer. The 
device specification for the printer would be f P: f . 
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01 ; HANDLER ADDRESS TABLE 



CT ATD 




0? PR 1 MTV 
UZ r r\ 1 IN 1 V 




$E430 




U A AC\ 








$E440 




e Ann 

1 4UU 




r\A rniTRV 




$E400 




F/i 1 n 

L4 I U 








$E410 




FA90 




Of. KFYRDV 

U / f 




$E420 




nnno 




08 


*= $031 A 


• 






OQ • 












1 0 HATARS 








031 A 


50 


20 


.BYTE 


ipi 


PRINTER 

1 1 \ 1 1 1 1 Li \ 


03 1B 


30E4 

\J U— 1^ 


30 


.WORD 


PR I NTV 


ENTRY POINT TABLE 


03 1D 


43 


40 


.BYTE 


'C 


CASSb 1 1 b 


031E 


40E4 


50 


• WORD 


CASETV 


ENTRY POINT TABLE 


0320 


45 


60 


.BYTE 


»E« 


DISPLAY EDITOR 


0321 


00E4 


70 


.WORD 


EDITRV 


ENTRY POINT TABLE 


0323 


53 


80 


.BYTE 


*S f 


SCREEN HANDLER 


0324 


10E4 


90 


.WORD 


SCRENV 


ENTRY POINT TABLE 


0326 


4B 


0100 


.BYTE 


»K» 


KEYBOARD 


0327 


20E4 


0110 


.WORD 


KEYBDV 


ENTRY POINT TABLE 


0329 


00 


0120 


.BYTE 


0 


FREE ENTRY 1 (DOS) 


032A 


00 00 


0130 


.BYTE 


0,0 




o"5?r 


00 


01 40 


.BYTE 


0 


FREE ENTRY 2 (850 MODULE) 


032D 


00 00 


0150 


.BYTE 


0,0 




032F 


00 


0160 


.BYTE 


0 


FREE ENTRY 3 


0330 


00 00 


0170 


.BYTE 


0,0 




0332 


00 


0180 


• BYTE 


0 


FREE ENTRY 4 


0333 


00 00 


0190 


.BYTE 


0,0 




0335 


00 


0200 


.BYTE 


0 


FREE ENTRY 5 


0336 


00 00 


0210 


.BYTE 


0,0 




0338 


00 


0220 


• BYTE 


0 


FREE ENTRY 6 


0339 


00 00 


0230 


.BYTE 


0,0 




033B 


00 


0240 


.BYTE 


0 


FREE ENTRY 7 



FIGURE 8.4A HANDLER ADDRESS TABLE (HATABS) 



*=$PRINTV 



E430 


9E 


EE 


.WORD 


PHOPEN-1 


E432 


DB 


EE 


.WORD 


PHCLOS-1 


E434 


9D 


EE 


• WORD 


BAD ST- 1 


E436 


A6 


EE 


.WORD 


PHWRIT-1 


E438 


80 


EE 


.WORD 


PHSTAT-1 


E43A 


9D 


EE 


.WORD 


BAD ST- 1 


E43C 


4C 


78 EE 


JMP 


PHINIT 



DEVICE OPEN 
DEVICE CLOSE 

DEVICE READ-NOT IMPLEMENTED 
DEVICE WRITE 
DEVICE STATUS 
SPECIAL-NOT IMPLEMENTED 
DEVICE INITIALIZATION 



FIGURE 8.4B PRINTER HANDLER ENTRY POINT TABLE 
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CIO uses a table called HATABS (figure 8.4A) to Indirectly calculate the 
handler entry point. This table uses a device specification as a key to find 
the address of the associated handler entry points. The device specification 
Is used to find the HATABS entry for the device we want to OPEN. CIO starts 
at the end of HATABS and looks for the first entry that matches the current 
device specification (In our case f P: f , the first entry In the HATABS). The 
address associated with the device spec Is a pointer to a list of handler 
entry points (the handler entry points for the printer are shown In figure 
8.4B) . 

CIO uses ICCOM, the I0CB command byte, to find which one of the handler 
entry points to vector thru. The entry point tables for all of the resident 
device handlers can be found In the O.S. listing. The positions in all the 
device handler entry point tables have the same meaning. For example, the 
first position in all of the device handler entry point tables Is the vector 
to the device handler OPEN routine. 

HATABS is located In RAM at $031 A and It contains room for 14 entries. 
At power-up and SYSTEM RESET the contents of HATABS Is Initialized as shown 
In figure 8.4. HATABS at this time has entries for all the resident handlers 
except the disk handler. The disk handler is never called via HATABS (see 
Chapter 9). 

Other entries may be added to HATABS by you or by the O.S. The O.S. may 
add entries as part of Its power-up or SYSTEM RESET function. Any new 
entries would start at $0329. Additions to HATABS might be entries for the 
disk drive (the File Manager or FMS) or the 850 module. 

i You can take advantage of the flexible nature of HATABS to add some new 
features to the O.S. One example (figure 8.5) shows how to add a null 
handler. A null handler is exactly what it sounds like, it performs NO 
FUNCTION! A null handler may be used to debug programs that use devices that 
have slow access speed. Instead of waiting for 50,000 disk accesses to find 
a bug, just run the output thru the null handler! 

Another use of HATABS is to change the function of an old entry In 
HATABS. Suppose you wanted to add a printer to your computer that had some 
special features not supported by the current printer handler. By changing 
the HATABS entry point table pointer, you can point all ! P: f I/O to your own 
printer handler. Appendix VII gives an example of a Qume printer handler 
that uses the front controller ports for speedy transfer of data to be 
printed. 
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nnnn 




1 0 


*= $600 




031 A 




20 HATABS 


$031A 








30 START 








0600 


A000 


40 

50 LOOP 


LDY 


#0 




0602 


B91A03 


60 


LDA 


HATABS, Y 




0605 


C900 


70 


CMP 


#0 


FREE ENTRY? 


0607 


F009 


80 


BEQ 


FOUND 




0609 


C8 


90 


I NY 






060A 


C8 


0100 


1 NY 






060B 


C8 


0110 


1 NY 




PO I NT TO NEXT HATABS ENTRY 


060C 


C022 


0120 


CPY 


#34 


AT END OF HATABS? 


060E 


D0F2 


0130 


BNE 


LOOP 


NO ... 


0610 


38 


0140 


SEC 




YES, FLAG ERROR TO CALLER 


0611 


60 


0150 
0160 ; 
0170 FOUND 


RTS 






0612 


A94E 


0180 


LDA 


#'N 


DEVICE NAME 


0614 


991A03 


0190 


STA 


HATABS, Y 




061 / 


C8 


0200 


1 NY 






0618 


A924 


0210 


LDA 


#NULLTAB&255 




061A 


991 A03 


0220 


STA 


HATABS , Y 


NULL HANDLER ENTRY TABLE 


061D 


C8 


0230 


1 NY 






061 E 


A906 


0240 


LDA 


#NULLTAB/256 




0620 


991 A03 


0250 


STA 


HATABS, Y 




0623 


60 


0260 
0270 I 


RTS 










0280 NULLTAB 






0624 


3206 


0290 


.WORD 


RTHAND- 1 


OPEN 


0626 


3206 

A_ W V/ 


0300 


.WORD 


RTHAND- 1 


CLOSE 


0628 


3406 


0310 


• WORD 


N0FUNC-1 


READ 


062A 


3206 


0320 


.WORD 


RTHAND-1 


WRITE 


062C 


3206 


0330 


.WORD 


RTHAND -1 


STATUS 


062E 


3406 


0340 


.WORD 


NOFUNC-1 


SPECIAL 


0630 


4C3306 


0350 
0360 ; 
0370 RTHAND 


JMP 


RTHAND 


INITIALIZATION 


0633 


A001 


0380 

0390 N0FUNC 


LDY 


#1 


SUCCESSFUL I/O FUNCTION 
FUNCTION NOT IMPLEMENTED 


0635 


60 


0400 


RTS 







FIGURE 8.5 NULL HANDLER 
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DOING CIO FROM BASIC 

Most of the CIO functions (OPEN, CLOSE, etc.) are available through 
calls from BASIC. BASIC lacks one set of the functions of CIO, the ability 
to do non-record I/O more than a byte at a time (GETCHRS and PUTCHRS). 

The ability to Input or output a buffer of characters at a time Is a 
nifty feature. For Instance, an assembly language routine can be loaded 
directly into memory from a disk file. In a BASIC program, an assembly 
language routine Is normally read Into a string and a USR call Is made to 
ADR(strlng). Since the address of a BASIC string may shift during program 
modification, the assembly language routine must be location Independent. 
This means memory reference instructions to addresses within the string will 
not work . 

The subroutine In figure 8.6 avoids the use of strings. This way the 
assembly module does not have to be location Independent. Control data Is 
POKEd Into an I0CB to read an assembly language routine directly into RAM at 
the address It was assembled. The BASIC subroutine in figure 8.6 can also be 
used to output data directly from memory with the user specif! ng both the 
location and the length of the data buffer. 



THE DEVICE HANDLERS 

The device handlers can be divided Into the resident and non-resident 
handlers. The resident handlers are present In the O.S. ROM. Any resident 
handlers can be called through CIO as long as the handler has an entry in 
HATABS. The resident device handlers are: 



(E: 


) 


DISPLAY EDITOR 


(S: 


) 


SCREEN 


(K: 


) 


KEYBOARD 


(P: 


) 


PRINTER 


(C: 


) 


CASSh 1 1 t 
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30 REM THIS PROGRAM LOADS PAGE 6 FROM THE FILE D:TEST 

100 DIM FILE$(20),CIO$(7):CIO$="hhh*LVd" ( Indicates Inverse video) 

106 REM CIO$ IS PLA,PLA,PLA,TAX,JMP $E456 (CIOV) 

110 F I LE$="D : TEST" : REM _ *F I LE NAME 

120 CMD=7:STADR=1536:GOSUB 30000 

130 IF ERROR <>1 THEN ? "ERROR - "; ERROR;" AT LINE "; 
135 ? PEEK(186)+PEEK(187)*256,PEEK(195) 
200 END 

300 REM _ CIO SETUP SUBROUTINE 

310 REM 

30000 REM ROUTINE BY M. EKBERG FOR ATARI 9-3-80 

30001 REM 

30002 REM THIS ROUTINE LOADS OR SAVES MEMORY FILE FROM BASIC 

30003 REM BY SETTING UP AN IOCB AND CALLING CIO DIRECTLY 

30004 REM 

30006 REM ON ENTRY CMD=7 MEANS LOAD MEMORY 

30008 REM _ CMD=11 MEANS SAVE MEMORY 

30009 REM _ STADR= THE ADDRESS TO LOAD OR SAVE MEMORY 

30010 REM _ BYTES= THE NUMBER OF BYTES TO SAVE OR LOAD 

30011 REM _ IOCB= THE IOCB TO USE 

30012 REM _ FILE$= DESTINATION FILE NAME 

30013 REM _ 

30014 REM ON EXIT ERR0R=1 MEANS SUCCESSFUL COMMAND 

30018 REM _ ERR0RO1 THEN ITS AN ERROR STATUS 

30019 REM 

30020 REM _ *** IOCB EQUATES *** 
30022 REM 

30024 I OCBX= I OCB* 16:1 CC0M=834+ I OCBX : I CSTA=835+ I OCBX 
30026 I CBAL=836+ I OCBX : I CBAH=837+ I OCBX 

30028 ICBLL=840+IOCBX: ICBLH=841+I0CBX 

30029 REM 

30030 AUX1=4:IF CMD=11 THEN AUX1=8 

30035 TRAP 30900: OPEN #I0CB,AUX1 , 0,F I LE$: I OCBX= I OCB* 1 6 

3004U TEMP=STADR:GOSUB 30500 

30090 POKE ICBAL,LOW:POKE ICBAH,HIGH 

30100 TEMP=BYTES : GOSUB 30500 

30130 POKE ICBLL,LOW:POKE ICBLH,HIGH 

30140 POKE ICCOM,CMD:ERROR=USR(ADR(CIO$), IOCBX) 

30 1 50 ERROR=PEEK ( I CS AT) : RETURN 

30200 REM 

30300 REM _ ***ROUTINE RETURNS HIGH, LOW BYTE OF 16 BIT NUMBER 
30400 REM 

30500 HIGH=INT(TEMP/256):L0W=INT(TEMP-HIGH*256):RETURN 
30550 REM 

30600 REM ***TRAP HERE IF ERROR IN ROUTINE**** 
30900 ERR0R=PEEK(195) 
30920 CLOSE # I OCB : RETURN 



FIGURE 8.6 BASIC DIRECT CIO CALL 
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The non-resident handlers are not present In the O.S. ROM, Non-resident 
handlers may be added by the O.S. during powei — up or SYSTEM RESET, or you can 
add your own device handler during program execution. Refer to figure 8.5 as 
an example of adding a handler to the O.S. 

The device handlers use I/O control data passed by CIO In the ZIOCB. 
The data In the ZIOCB Is used to perform I/O functions such as OPEN, CLOSE, 
PUT, and GET. Not all of the device handlers support all the I/O commands 
(e.g. trying to PUT a character to the keyboard results In an Error 146, 
Function Not Implemented). Section 5 of the O.S. Manual contains a list of 
the functions supported by each device handler. 



SERIAL I/O SYSTEM ROUTINE - - SIO 



SIO AND THE DEVICE HANDLERS 

SIO handles serial bus communication between the serial device handlers 
In the computer and the serial bus devices. SIO communicates to Its caller 
through the device control block (DCB). SIO uses the I/O control data In the 
DCB to send and receive commands and data over the serial bus. The calling 
sequence Is: 

;caller has set up the DCB to do function 
JSR SIOV ; system vector to SIO 

BM I ERROR ;N bit set Indicates error In I/O execution 

The DCB contains I/O control Information for SIO and must be setup 
before the call to SIO. Figure 8.3 shows the contents of the DCB for some 
common I/O operations. 

You need to understand the structure of the DCB to send commands to SIO. 
The DCB Is described In section 9 of the O.S. Manual. Figure 8.7 
demonstrates a simple assembly language routine to output a line to the 
printer by setting up the DCB and calling SIO. 
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OOOO 

E459 
009B 
0040 
004E 
001 C 
0300 
0301 
0302 
0303 
0304 
0305 
0306 
0307 
0308 
0309 
030A 
030B 

3000 
3001 
3005 
3009 

300B 
300D 
3010 
3012 
3015 
3017 
301A 
301C 
301F 
3022 
3024 
3027 
3029 
302C 
302E 
3031 
3033 
3036 
3038 
303B 
303E 
3040 
3041 



455841 
4D504C 
452031 
329B 

A940 

8D0003 

A901 

8D0103 

A94E 

8D0A03 

A901 

8D0B03 

8D0703 

A51C 

8D0603 

A900 

8D0403 

A930 

8D0503 

A980 

8D0303 

A957 

8D0203 

2059E4 

3001 

00 

00 



05 

10 ;THIS ROUTI 
20 SIOV 
30 CR 
40 PRNTID 
45 MODE 
50 PTIMOT 
60 DDEVIC 
70 DUN IT 
80 DCOMND 
90 DSTATS 
0100 DBUFLO 
0110 DBUFHI 
0120 DTIMLO 
0130 DTIMHI 
0140 DBYTLO 
0150 DBYTHI 
0160 DAUX1 
0170 DAUX2 
0180 ; 
0190 MESS 



0200 ; 

0220 

0230 

0240 

0250 

0260 

0270 

0275 

0280 

0290 

0300 

0310 

0320 

0330 

0340 

0350 

0360 

0370 

0380 

0390 

0410 

0420 

0430 GOOD 
0440 ERROR 



*= $3000 

NE PRINTS A LI 
$E459 
$9B 
$40 
$4E 
$001C 
$300 
$301 
$302 
$303 
$304 
$305 
$306 
$307 
$308 
$309 
$30A 
$30B 



LDA 
STA 
LDA 
STA 
LDA 
STA 
LDA 
STA 
STA 
LDA 
STA 
LDA 
STA 
LDA 
STA 
LDA 
STA 
LDA 
STA 
JSR 
BMI 
BRK 
BRK 



ARBITRARY START 

NE TO THE PRINTER BY CALLING SIO 
SIO VECTOR 
EOL 

PRINTER SERIAL BUS ID 
NORMAL MODE 
TIMEOUT LOCATION 
DEVICE SERIAL BUS ID 
SERIAL UNIT NUMBER 
SIO COMMAND 
SIO DATA DIRECTION 
BUFFER LOW ADDRESS 
BUFFER HIGH ADDRESS 
SIO TIMEOUT 



BUFFER LENGTH 

AUXILARY BYTE' 
AUXILARY BYTE- 



-PRINTER MODE 
-NOT USED 



.BYTE "EXAMPLE 12", CR 



#PRNTI D SET BUS ID 
DDEVIC 

#\ SET UNIT NUMBER 

DUN IT 
#MODE 
DAUX1 
#1 

DAUX2 
DTIMHI 
PT I MOT 
DTIMLO 
#MESS&255 

DBUFLO SET MESS AS BUFFER 

#MESS/256 

DBUFH I 

SET SIO DATA DIRECTION FOR 

PERIPHERAL TO RECEIVE 
SIO COMMAND WRITE 



PRINTER MODE NORMAL 
UNUSED 

TIME0UT<256 SECS 
SET SIO TIMEOUT FOR PRINTER 



#$80 
DSTATS 
#'W 
DCOMND 
SIOV 
ERROR 



CALL SIO 



FIGURE 8.7 SIO CALL TO DUMP LINE TO PRINTER 
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SIO INTERRUPTS 



SIO uses three IRQ Interrupts to send and receive serial bus 
communications to serial bus devices. They are: 



IRQ 

VSERIR 
VSEROR 
VSEROC 



Locat Ion, 
Length 



$020A,2] 
$020C,2l 
$020E,2l 



Function 

SERIAL INPUT READY 
SERIAL OUTPUT NEEDED 
TRANSMISSION FINISHED 



All program execution Is halted while SIO uses the serial bus for 
communication. For output, SIO gives the POKEY serial output shift register 
(SEROUT) a byte to send on the serial bus, then It enters an Idle loop until 
it receives an IRQ (VSEROR) from POKEY telling SIO that SEROUT is free for 
another byte. The IRQ causes a jump to the SIO routine to load SEROUT with 
another byte. This loop is executed until all the bytes specified In the DCB 
buffer length have been sent. VSEROR Is an IRQ indicating that the 
transmission of the byte over the bus is complete. 

The SIO execution for input is similar. POKEY Informs SIO a byte has 
been received in the serial input shift register (SERIN) by generating an IRQ 
(VSERIR). SIO stores the byte In a buffer and then SIO idles in a loop until 
the next IRQ tells It another byte has been received. 

You may have noticed from the above explanation that SIO wastes some 
time idling while waiting for POKEY to send or receive information on the 
bus. As the vectors for the three SIO IRQ service routines are RAM vectors, 
they can be used by some handlers to Improve system I/O performance. 

Indeed, this Is how the 850 module Is able to do 'concurrent I/O 1 . The 
850 module handler takes over the SIO IRQ vectors and points these IRQ 
vectors to the module's own IRQ routines while in concurrent I/O. The 850 
Module handler can then send commands over the bus. While waiting for the 
850 Module to do the command, the 850 Module handler allows the executing 
program to continue. 
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SECTION 8.3 - - INTERRUPTS 



INTRODUCTION 

In the previous section we have seen how SIO uses Interrupts to 
coordinate transfer of data over the serial bus. The computer also has other 
catagorles of Interrupts. You can use several of these other Interrupts to 
add some powerful features to your application. It should be noted that 
there are two types of Interrupts, the maskable (IRQ) and the non-maskable 
(NMI ) Interrupts. The PCS Interrupts are: 



Name (vector) Type Function Used By 

DISPLAY LIST (VDSLST) NMI Graphics timing User 

SYSTEM RESET (none) NMI System- In It. PCS 

VERT I UAL BLANK ( VVBLK I , VVBLKD) NMI Graphics display PCS, user 

SERIAL OUTPUT READY (VSERIN) IRQ Serial Input PCS 

SERIAL INPUT READY (VSEROR) IRQ Serial Input PCS 

SERIAL OUTPUT COMPLETE (VSEROC) IRQ Serial output PCS 

POKEY TIMER 1 (VTIMR1) IRQ Hardware timer User 

POKEY TIMER 2 (VTIMR2) IRQ Hardware timer User 

*POKEY TIMER 4 (VTIMR4) IRQ Hardware timer User 

KEYBOARD (VKEYBD) IRQ Key hit PCS 

BREAK KEY (none) IRQ <BREAK> hit PCS 

SERIAL BUS PROCEED (VPRCED) IRQ Device proceed Unused 

SERIAL BUS INTERRUPT (VINTER) IRQ Device Interrupt Unused 



* This IRQ Is not vectored In the current O.S. 



If you are not familiar with Interrupts, Section 6 of the O.S. Manual 
contains Information on them. Working with Interrupts can be tricky. For 
example, If you accidentally disable the keyboard IRQ Interrupt, the computer 
will Ignore all the keys except the <BREAK> key. Although this may be useful 
sometimes, It may make debugging your program a bit difficult! 



THE IRQ INTERRUPT HANDLER 

The O.S. has an IRQ Interrupt handler that processes the various IRQs. 
The IRQ Handler has RAM vectors for all of the IRQs except the <BREAK> key 
IRQ. The IRQ vectors are set to their Initial values during both powei — up 
and SYSTEM RESET. The locations of the IRQ RAM vectors are described In 
figure 8.9B. 
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The IRQs vectors are: 

VIMIRQ — Immediate IRQ vector. All IRQ's vector 
thru this location. VIMIRQ normally points to the IRQ 
Handler. You can 'steal 1 this vector to do your own IRQ 
Interrupt processing. 

VSEROR — Pokey Serial Output Ready IRQ vector, (see 
section 8.2) 

VSERIN -- Pokey Serial Input Ready IRQ vector, (see 
section 8.2) 

VSEROC — Pokey Serial Output Complete IRQ vector, 
(see section 8.2) 

VTIMR1 — Pokey Timer 1 IRQ vector, (see section 8.7 
for Information on the Pokey Timers) 

VTIMR2 Pokey Timer 2 IRQ vector. 

VTIMR4 -- Pokey Timer 4 IRQ vector. 

VKEYBD — Keyboard IRQ vector. Pressing any key 
except <BREAK> causes this IRQ. VKEYBD can be used to 
pre-process the key code before It Is converted to 
ATASCII (by the O.S.). VKEYBD normally points to the 
O.S. keyboard IRQ routine. 

VPRCED — Peripheral Proceed IRQ vector. The 
proceed line Is available to peripherals on the serial 
bus. This IRQ is unused at present and normally points 
to an RTI . 

V INTER — Peripheral Interrupt IRQ vector. The 
Interrupt line Is also available on the serial bus. 
VINTER also normally points to an RTI. 

VBREAK 6502 BRK instruction IRQ vector. Whenever 
a $00 opcode (the software break instruction) is 
executed, this Interrupt occurs. VBREAK can be used to 
set break points for a debugger. VBREAK normally points 
to an RTI . 
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The IRQs are enabled and disabled as a group by the 6502 Instructions 
CLI and SEI respectively. The IRQs also have individual enable/disable bits. 

Section I I I of the hardware manual shows the IRQs and their enable/disable 
bits. 

Register (IRQEN) contains most of the IRQ enable/disable bits and Is a 
write-only register. The O.S. keeps a shadow of IRQEN for you to read In 
POKMSK. POKMSK Is written to IRQEN during vertical blank. 



USING THE IRQS 

Many applications require that the keyboard be 1 Id lot-proofed 1 . This 
means a user can press any key or combination of keys and the program will 
accept valid key sequences and ignore Invalid ones. You can use a couple of 
the IRQ vectors to 1 Idiot-proof 1 your program. The example in figure 8.8 
uses the VKEYBD IRQ vector to disable the control key. The routine also 
masks the <BREAK> key by stealing the YIMIRQ vector and Ignoring the <BREAK> 
key interrupt. 



THE NMI HANDLER 

The O.S. has an NMI handler for handling the non-maskable interrupts. 
Unlike the IRQs, the NMIs cannot be 'masked' (disabled) on the 6502. All the 
NM Is except SYSTEM RESET can be disabled on ANTIC. 

Two of the NMIs, the display list interrupt (DLI) and the vertical blank 
(VBLANK) Interrupt, have RAM vectors that you can use. In fact, VBLANK can 
be Intercepted In two places, Immediate or Deferred VBLANK. The NMI vectors 
are: 

Name Vector 

SYSTEM RESET none 

DISPLAY LIST INTERRUPT VDSLST [$0200] 

VERTICAL BLANK 

IMMEDIATE VVBLK I [$0222] 

DEFERRED VVBLKD [$0224] 



The SYSTEM RESET NMI doesn't have a RAM vector. SYSTEM RESET always 
results In a jump to the monitor warmstart routine (section 8.5) The DLI and 
the VBLANK Interrupts are covered In Chapter 5 and Appendix I respectively. 
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no 1 n 
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JUMP+1 


REP 
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Auuyuz 
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UZZU 


LDA 


VKEYBD+1 
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Uoz2 
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OU44U0 
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STA 


JUMP+2 




A£ ok 
0625 




0240 


LDA 


#REP&255 


i VECTOR KEY IRQ 


f\C 0*7 

Uoz7 


oDOoOz 


0250 


STA 


VKEYBD 


LOW BYTE OF VECTOR 


a^ oa 
UOZA 


AyuD 


UzoU 


LDA 


#REP/256 


UozO 
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ouuyuz 
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Uz/U 


STA 
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OU 
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UDJ>U 
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#$80 


CHECK IF CONTROL HIT 


UD^>t 
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UjZU 


BEQ 


JUMP 


IF NOT HIT THEN GO 


UD4U 


Do 


n77n 
Uj^U 


PLA 




ELSE IGNORE CON. KEY 


r\c a 1 
U041 


a a 
4U 


AT >1 A 

U.24U 


RTI 






UD4Z 


4U4ZUO 


n7cn ti imd 

U->DU JUmr 


JMP 


JUMP 


THIS CALLS THE OLD KEY IRQ 


UD42 


/ft 
40 


077K 1 on 
U-> / D 1 Ky 


PHA 




ALL IRQS COME HERE 


UD4D 


AUULUZ 


U->OU 


LDA 


1 RQST 


CHECK IF <BREAK> 


a a 

ub4y 


4 Art yl 

1 004 


AT A A 
0^90 


BPL 


BREAK 


IF <BREAK> IRQ BR. 


064B 


68 


0405 


PLA 




ELSE CALL OLD IRQ VECTOR 


064C 


4C4C06 


0410 NBRK 


JMP 


NBRK 


CALL OLD IRQ VECTOR 


064F 


A97F 


0430 BREAK 


LDA 


#$7F 


HERE IF <BREAK> 


0651 


8D0ED2 


0440 


STA 


IRQST 


SHOW NO <BREAK> 


0654 


A510 


0450 


LDA 


P0KMSK 




0656 


8D0ED2 


0460 


STA 


IRQEN 




0659 


68 


0462 


PLA 






065A 


40 


0464 


RTI 




RETURN AS 1 F NO <BREAK> 


065B 




0470 


*= 


$02E2 




02E2 


0006 


0480 


• WORD 


START 





FIGURE 8.8 IDIOT-PROOFING THE KEYBOARD 
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SECTION 8.4 - - THE SYSTEM VECTORS 



The O.S. has two types of vectors, ROM vectors and RAM vectors. ROM 
vectors are locations which contain JMP Instructions to system routines. RAM 
vector contain two-byte addresses to system routines, handler entry pointers 
(see CIO section 8.2), or to Initialization routines. 

Both the ROM and RAM vector addresses are guaranteed not to change If 
ATARI releases a new O.S. but the contents of these vectors are free to 
change. The vectors, their contents and a brief description of their 
function are described in figures 8.9A and 8.9B. 



ROM VECTORS 



Name 



Locat I on 



Use 



SETVBV 
SYSVBV 
XITVBV 
SIOINV 
SENDEV 
INTINV 
CIOINV 
BLKBDV 
WARMSV 
COLDSV 
RBLOKV 
CSOP I V 



SIOV 



D I SK I V 
DSK I NV 
CIOV 



$E450 
$E453 
$E456 
$E459 
SE45C 
$E45F 
$E462 
$E465 
$E468 
$E46B 
$E46E 
$E471 
$E474 
SE477 
$E47A 
$E47D 




An example of using a ROM vector is: 



JSR CIOV 



FIGURE 8.9A ROM VECTORS 
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RAM VECTORS 



Name Location Value 



Use 



VDSLST 

VPRCED 

V I NTER 

VBREAK 

VKEYBD 

VSERIN 

VSEROR 

VSEROC 

VTIMR1 

VTIMR2 

VTIMR4 

VIMIRQ 

VVBLK I 

VVBLKD 

CDTMA1 

CDTMA2 

CASINI 

DOSINI 

DOSVEC 

RUNVEC 

INIVEC 

HATABS 



$0200 
$0202 
$0204 
$0206 
$0208 
$020A 
$020C 
$020E 
$0210 
$0212 
$0214 
$0216 
$0222 
$0224 
$0226 
$0228 
$0002 
$000C 
$000A 
$02E0 
$02E2 
$031 A 
$03 1B 
$031 D 
$03 1E 
$0320 
$0321 
$0323 
$0324 
$0326 
$0327 
$0329 
$032B 
$032E 
$0331 
$0234 
$0237 
$032A 
$0340 
$0340 



$E7B3 
$E7B3 
$E7B3 
$E7B3 
$FFBE 
$EB11 
$EA90 
$EAD1 
$E7B3 
$E7B3 
$E7B3 
SE6F6 
$E7D1 
$E93E 
$xxxx 
$xxxx 
$xxxx 
$xxxx 
$xxxx 
$xxxx 
$xxxx 

tpt 

$E430 
»C« 
$E440 
•E' 

$E400 
'S« 

$E410 
•K* 

$E420 

•x' 

•x» 

'x' 

»x» 

»x' 

•x» 

»x» 

»x» 

'X' 



Display List Interrupt NMI Vector 

Proceed Line IRQ Vector — Unused at present 

Interrupt Line IRQ Vector — Unused at Present 

Software Break Instuctton IRQ Vector 

Keyboard IRQ Vector 

Serial Input Ready IRQ Vector 

Serial OutputReady IRQ Vector 

Serial Output Complete IRQ Vector 

POKEY Timer 1 IRQ Vector 

POKEY Timer 2 IRQ Vector 

POKEY Timer 4 IRQ Vector 

Immediate IRQ Vector to IRQ Handler 

Vertical Blank NMI Vector 

Deferred Vertical Blank Vector 

System Timer 1 JSR Address 

System Timer 2 JSR Address 

Vector for bootable cassete program initialization 

Disk In Itl I ization Vector 

Disk Software Run Vector 

DUP File Load and GO Run Vector 

DUP File Load and Go Initialization Vector 

Printer Device I .D 

Address of Printer Entry Points Table 
Cassette Device I .D. 
Address of Cassette Entry Points Table 
Display Editor I .D. 

Address of Display Editor Entry Points Table 
Screen Hand I er I .D. 

Address of Screen Display Entry Point Table 
Keyboard Handler I .D. 

Address of Keyboard Handler Entry Point Table 
HATABS Unused Entry 1 



1! 


II 


•1 


2 


tf 


II 


II 


3 


If 


II 


II 


4 


II 


II 


II 


5 


II 


II 


II 


6 


II 


II 


II 


7 


II 


II 


II 


8 


II 


II 


II 


9 



An x Indicates content varies. 
An example of using a RAM vector 
JSR CALL 
CALL JMP (DOSINI) 



Is: 



FIGURE 8.9B RAM VECTORS 
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0010 ; WRITTEN BY... MICHAEL EKBERG 


0600 




0030 START 


$600 


OOOC 




0040 DOS INI 


$0C 


02E7 




0050 MEMLO 


$2E7 


3000 




0060 NEWMEM = 


$3000 ; ALTER THIS TO GET SIZE 






0070 ] 


[THIS ROUTINE RESERVES SPACE FOR ASSEMBLY ROUTINES 






/"X 0\ 

0090 \ 


[ BY RESETING THE MEMLO POINTER. IT RUNS AS 






0100 | 


; AN AUTORUN.SYS FILE. IT ALSO RESETS MEMLO ON [RESET!!. 






0120 | 


; MEMLO IS 


SET TO THE VALUE OF NEWMEM. 






0130 ; 










0140 j 


[THIS PART 


IS PERMANENT, IE. NEEDS TO BE RESIDENT. 






0150 j 


; THE SYSTEM DOS IN IT VECTOR HAS BEEN STOLEN 






0160 j 


; AND STORED IN THE LOCATION INITDOS+1 42. 






0180 j 


; DOS IS INITIALIZED AND MEMLO IS INITIALIZED 






0190 | 


; INITDOS EXECUTES ON [RESET] . 


0000 




0200 
0210 


*= 

INITDOS 


START 


0600 


200D06 


0220 


JSR 


CYNTHIA ; DO DOS INITLIST 


0603 


A900 


0230 


LDA 


#NEWMEM&255 


0605 


8DE702 


0240 


STA 


MEMLO 


0608 A930 


0250 


LDA 


#NEWMEM/256 


060A 


8DE802 


0260 


STA 


MEMLO+1 






0270 CYNTHIA 




060D 


60 


0280 


RTS 








0290 j 


[THIS PART 


IS EXECUTED AT POWER UP ONLY AND 






0300 \ 


; CAN BE DELETED AFTER POWER-UP. 






0330 i 


; THIS ROUTINE STORES THE CONTENTS OF DOS INI INTO A JSR 






0350 ; 


; AT LOCATION INITDOS+1. IT THEN REPLACES DOSINI WITH 






0370 : 


! IT'S OWN 


VALUE, THE LOCATION INITDOS. 






0390 JACKIE 




060E 


A50C 


0400 


LDA 


DOSINI ; SAVE DOSINI 


0610 


8D0106 


0410 


STA 


INITDOS+1 


0613 


A50D 


0420 


LDA 


DOSINI+1 


0615 


8D0206 


0430 


STA 


INITDOS+2 


0618 


A900 


0440 


LDA 


#INITD0S&255 ; SET DOSINI 


061A 


850C 


0450 


STA 


DOSINJ 


061 C 


A906 


0460 


LDA 


#INITD0S/256 


061E 


850D 


0470 


STA 


DOS 1 N 1 +1 


0620 


A500 


0480 


LDA 


NEWMEM&255 ; SET MEMLO 


0622 


8DE702 


0490 


STA 


MEMLO 


0625 


A930 


0500 


LDA 


#NEWMEM/256 


0627 


8DE802 


0510 


STA 


MEMLO+1 


062A 


60 


0520 


RTS 




062B 




0530 




$2E2 


02E2 


0E06 


0540 


.WORD JACKIE ; SET RUN ADDRESS 


02E4 




0550 


.END 





FIGURE 8.10 MEMLO MOVER 
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SECTION 8.5 - - THE MONITOR 

The O.S. monitor Is a program in ROM that handles both the system 
power-up and SYSTEM RESET sequences. The power-up and SYSTEM RESET sequences 
are similar In function and In fact share much of the same code. Appendix IV 
has a flowchart of the power-up and SYSTEM RESET routines. 

The power-up routine (also known as coldstart) Is Invoked either by 

turning on the computer or by jumping to COLDSV [$E477]. COLDSV Is the 

system routine vector to the power-up routine. Important Items to remember 
about the powei — up are: 

1. ALL of memory Is cleared except locations 
$0000-$000F 

2. Both a cassette and disk boot are attempted. 
BOOT?C$0009U Is a flag that indicates the success or 
failure of the boots. Bit 0=1 If a successful cassette 
boot; Bit 1=1 If a successful disk boot. 

3. C0LDSTt$0244] Is a flag that tells the Monitor 
that It is In the middle of power-up. COLDST=0 means 
System Reset, C0LDST<>0 means power-up. An Interesting 
use of COLDST is to set It to a non-zero value during 
execution of an application program. This will cause a 
SYSTEM RESET to become a power-up. This technique may 
add a measure of security by preventing a user from 
gaining control of the computer while an application Is 
runn tng. 



Pressing the < SYSTEM RESET> key causes a SYSTEM RESET (also known as 
warmstart) . Some of the key facts to remember about SYSTEM RESET In the 
flowchart In Appendix IV are: 

1. The O.S. RAM vectors are downloaded from ROM both 
during SYSTEM RESET and power-up. If you wish to f steal f 
a vector, some provision must be made to handle SYSTEM 
RESET. See Chapter 9 on how to handle SYTEM RESET. 

2. MEMLO,MEMTOP,APPMHI,RAMSIZ, and RAMTOP are reset 
during System Reset. If you wish to alter these user RAM 
pointers to reserve some space for assembler modules 
called by BASIC, some provision must be made to handle 
SYSTEM RESET. Figure 8.10 is an example on how to do this. 
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SECTION 8.6 - - THE SYSTEM DATABASE 

The system database contains many locations that store Information of 
Interest to the user. The locations may be accessed directly by Assembly 
language programs or by PEEK and POKE In BASIC. 

The system database occupies RAM pages 0 thru 4 ($0000-$03FF) . The 
database contains system flags, I/O buffers, I/O parameters, etc. The user 
can use some of these locations to provide features not supplied by either 
the O.S. or a program environment (i.e. BASIC). Figure 8.11 describes some 
of these elements of the database. 

DATA BASE CHART 



Name 

MEMLO 
MEMTOP 
APPMH I 
RAMTOP 
RAMSIZ 
POKMSK 
BRKKEY 



Location 
,Slze 

$02E7,2 
$02E5,2 
$000E 
$006A,2 
$02E4,1 
$0010,1 
$0111,1 



Intt. by Value Function 



I RQEN $D20E 
PTIMOT $001 C 
CIOCHR $002F 

ZIOCB $0020,16 



CKEY 

CASSBT 

KBCODE 

CH 

CH1 

SHLOK 

KEYDEL 

SSFLAG 

ATRACT 

SRTIMR 

COLDST 

WARM ST 

CHBAS 

CRITIC 



$004A,1 

$004B 

$D209,1 

$02FC 

$02F2,1 

$02BE,1 

$02F1,1 

$02FF,1 

$004D , 1 

$022B,1 

$0244,1 

$0008,1 

$02F4,1 

$0042 



R,P 


X 


User Free Memorv Low Address 


R,P 


x 


User Free Memorv HIah Address 


P.R 


$00 

w w 


User Free Memorv Screen lower 1 Imlt 

Wwwl 1 1 ww l iwlllwl y wwl wwll 1 vn vl 1 1 III 1 1 


P.R 


x 


DIsDlav Handler Tod of RAM Address (msb) 

mm | | Sari Y 11 V«4 • • >■ | 1 1 ^m ^0 I • »• t « * Xrf 1 * ill ' mm w 


P,R 


X 


Top of RAM Address (msb) 


P,R 


X 


O.S. IRQ enable shadow 


P,R 


$FF 


BREAK key flag; $FF means no 






BREAK key hit 


P,R 


X 


ANTIC IRQ enable bit register 


P.R 


X 


Printer timeout value for SI0 




X 


CIO temp storage for PUT a single 






char function 






CIO ZERO page I/O BLOCK 


P,R 


X 


Boot Flag; bit 0 Is cassette, 






bit 1 Is DOS 


P 


X 


Monitor Cassette boot flag 


P 




Cassette boot f I ag 




X 


Keyboard code register 


P,R 


$FF 


Current key value 




X 


Last keyboard value 


P,R 


$40 


Shift lock 




$03 


Keyboard sotware debounce timer 




X 


Start/ stop flag for display 






ATRACT mode flag 




X 


ATRACT mode timeout timer 






In 1+ flag 






Inlt flag 


P,R 


$E0 


Pointer to character base 


P,R 




Critical I/O region flag 



P means powei — up 

R means SYSTEM RESET 

x means value varies 



FIGURE 8.11 SYSTEM DATA BASE 
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MEMORY POINTERS 

The O.S. uses five locations to keep track of the user and display 
memory, MEMLO, MEMTOP, APPMHI, RAMTOP, and RAMSIZ. Their relationships are 
shown In figure 8.12, a simple system memory map. 

MEMLO Is a two-byte location that the O.S. uses to Indicate where an 
application program may begin. Used carefully, MEMLO can be used to create 
areas for assembly language modules that may be called from BASIC. BASIC 
uses the value of MEMLO to determine the starting location of a program (see 
the BASIC chapter for the structure of a BASIC program). If we desire to set 
MEMLO to a higher address, we must set It before the BASIC cartridge Is run. 
MEMLO has to be used carefully because It Is reset by both power-up and 
SYSTEM RESET. 

If the system will be booted from a disk drive then the AUTORUN.SYS 
facility can be used to set MEMLO to a predefined value. Because the DOS 
also resets MEMLO daring SYSTEM RESET via the DOS INI vector, DOS INI needs to 
f stolen f . DOSINI contains the address of the DOS Initialization code called 
as part of the monitor system Initialization. DOS still needs to be 
Initialized as part of SYSTEM RESET. The contents of DOSINI must be moved 
Into the two-byte address of a JSR Instruction as part of the powei — up. 
DOSINI Is then set to the address of the JSR Instruction for the 
initialization code and MEMLO Is set to the predefined value. When a SYSTEM 
RESET occurs, the new initialization code Is called and the first Insructlon, 
JSR OLDDOSINI, initializes DOS. The new Initialization code sets MEMLO to 
the predefined value and RTSs to the old initialization sequence. Figure 
8.10 Is an example on how to do this. 

The above technique can also be used with MEMTOP, the user high memory 
pointer. Space for assembly modules and data can be set aside by lowering 
MEMTOP from the values set by power-up and SYSTEM RESET. Using MEMTOP 
Instead of MEMLO creates one problem. MEMTOP fluctuates due to both the 
amount of RAM In the system and the graphics mode of the display. This makes 
It difficult to predict Its value before actually examining the location 
unless you make some assumptions about the system. As a result all assembly 
modules may need to be relocatable. 

APPMHI Is a location which contains an address that specifies the lowest 
address the display RAM may be placed. Setting APPMHI Insures that the 
display handler will not clobber some of your program code or data. 

RAMSIZ, like MEMTOP, can also be used to reserve space for assembly 
modules. The advantage of RAMSIZ over MEMTOP Is that the space saved by 
moving RAMSIZ down Is above the display. Space saved by moving MEMTOP down 
remains below the display. The display area expands and contracts depending 
on the graphics mode. 
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MEMORY MAP 



OS 



BASIC 



RAM 



MEMLO 2E7,2E8 



APPMHI OE,OF 



MEMTOP 2E5,2E6 
SDLST 230,231 



SAVMSC 58,59 



TXTMSC 294,295 



RAMTOP 6A 
RAMSIZ 2E4 



PAGE 
SIX 



BASIC 
TOKEN 
PROGRAM 



FREE 
RAM 



DISPLAY 
LIST 



SCREEN 
RAM 



TEXT 
WINDOW 



80,81 LOMEM 



90,91 
OE,OF 



2E5,2E6 



MEMTOP 
APHM 

I 

I 

FRE(O) 
I 
I 

HIMEM 



OS AND BASIC POINTERS (DOS PRESENT) 



FIGURE 8-12 
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MISCELLANEOUS 

BRKKEY Is a flag that Is set when the O.S. senses that the <BREAK> key 
has been pressed. BRKKEY f s normal value Is $FF. If It changes, then the 
<BREAK> key has been pressed. The <BREAK> key IRQ (not the software 
Instruction BRK IRQ) must be enabled for the O.S. to sense the <BREAK> key. 

The computer's printer timeout value Is stored In a RAM location called 
PTIMOT. It contains the value of the timeout period for SIO In seconds. It 
may be altered to Increase or decrease the timeout period by placing a new 
value In PTIMOT. PTIMOT Is Initialized to 30 seconds, and Is updated each 
time the printer Is opened. Typical timeout for the 825 Is 5 seconds. 
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1 POKE 752,1 .-GOTO 3 

3 ? "t":REM clear screen 

4 ? "HOUR" ; : I NPUT HOUR:? "MINUTE ";: INPUT MIN:? "SECOND"; : I NPUT SEC 

5 CMD=1:GOSUB 45 

6 ? "t";HOUR;" : ";MIN;" : ";SEC:? " ":? " " 

7 CMD=2:G0SUB 45 

9 ? "";HOUR;":";MIN;":";SEC;" ":GOTO 7 

10 REM THIS IS A DEMO OF THE REAL TIME CLOCK 

20 REM THIS ROUTINE ACCEPTS AN INITIAL TIME I HOUR, IMI N, I SEC 
30 REM IT SETS THE REAL TIME CLOCK TO ZERO 

40 REM THE CURRENT VALUE OF RTCLOCK IS USED TO ADD TO THE INITIAL TIME TO GET 
THE CURRENT TIME HOUR, MIN, SEC 
45 HIGH=1536:MED=1537:L0W=1538 
50 REM 

60 REM ******ENTRY POINT****** 
65 REM 

70 ON CMD GOTO 100,200 

95 REM 

96 REM **** INITIALIZE CLOCK***** 

97 REM 

100 POKE 20,0:POKE 19,0:P0KE 18,0 

105 DIM CL0CK$(50) 

106 CLOCK$=" " :(SUB 300 

110 IHOUR=HOUR: IMI N=MI N: I SEC=SEC: RETURN 

197 REM 

198 REM *******READ CLOCK***** 

199 REM 

200 REM 

201 A=USR ( ADR ( CLOCK $ ) ) 

2 1 0 T I ME= < ( ( ( PEEK ( H I GH ) *256 ) +PEEK ( MED ) > *256 ) +PEEK ( LOW ) ) / 59 . 923334 
220 HOUR= I NT( T I ME/3600 ) : T I ME=TI ME-( HOUR*3600 ) 
230 M I N= I NT(TI ME/60 ) : SEC= I NT(TI ME-(M I N*60 ) ) 

235 SEC=SEC+ISEC:IF SEO60 THEN SEC=SEC-60 : M I N=MI N+1 

236 M I N=M I N+ I M I N : I F MIN>60 THEN M I N=M I N-60 : H0UR=H0UR+1 

237 HOUR=HOUR+ 1 HOUR 

240 HOUR=HOUR-( I NT(H0UR/24) )*24 
250 RETURN 



FIGURE 8.13 - - REAL TIME CLOCKS 

300 F0RI=1 TO 38 : READ Z:CLOCK$( I , I )=CHR$(Z) :NEXT I : RETURN 

310 DATA 104,165,18,141,0,6,165,19,141,1,6,165 

320 DATA 20,141,2,6,165,18,205,0,6,208,234 

330 DATA 165,19,205,1,6,208,227,165,20,205,2,6,208,220,96 



8-30 



OPERATING SYSTEM 



SECTION 8.7 - - TIMERS 



THE SYSTEM TIMERS 

There are two types of timers provided for you to use. System timers 
run at the frequency of the T.V. frame. For North American television (NTSC) 
the rate Is 59.923334 hz. European (PAL) televisions run at 50 hz. The 
POKEY timers are clocked by frequencies setable by the user. 



There are 6 system timers: 



Name 

RTCLOK 
CDTMV1 
CDTMV2 
CDTMV3 
CDTMV4 
CDTMV5 



Location 

C$0012,3] 
I $021 8,2] 
I$021A,2] 
I$021C,2] 
I$021E,2] 
I $0220, 2] 



Vector or flag 
none 

CDTMA1 [$0226,2 
CDTMA2 C$0228,2. 
CDTMF3 C$022A,H 
CDTMF4 C$022C,1] 
CDTMF5 C$022E,1] 



All of the system timers are clocked as part of the vertical blank 
(VBLANK) process. If the VBLANK process Is disabled or Intercepted, the 
timers will not be updated. 

The real time clock(RTCLOK) and system timer 1 (CDTMV1) are updated 
during Immediate VBLANK, Stage 1. RTCLOK counts up from 0 and Is a three 
byte value. When RTCLOK reaches Its maximum value (16,777,216) It will be 
reset to zero. RTCLOK can be used as a time piece as example 8.13 shows. 

Because the system timers are updated as part of the VBLANK process, 
special care Is needed to set them correctly. A system routine called SETVBV 
C$E45C] Is used to set them. The call to SETVBV Is: 

REG's:X,Y contain the timer value. 

A contains the timer number: 

A=1-5 - - TIMERS 1-5 



ex.: 



LDA #1 ;Set system timer 1 
LDY #0 

LDX #02 ; value Is $200 VBLANKS 

JSR SETVBV ;Call system routine to set timer 
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5 ? "t" :REM BASIC ROUTINE 

7 REM BY M.EKBERG FOR CARL A 

10 X=10: FOR 1=1 TO 2 STEP 0 

20 T0P=10: FOR J=1 TO TOP : NEXT J 

50 IF STICK(0)=13 THEN X=X+1 :REM 

51 IF STICK(0)=14 THEN X=X-1 :REM 

52 IF X<1 THEN X=1:REM 

53 IF X>255 THEN X=255:REM 

54 REM 

56 ? »";INT(3600/X); M BEATS/MINUTES 
60 POKE 0,X:REM 
70 NEXT I :REM 



SET THE RATE OF A METRONOME 



SOFTWARE DELAY LOOP 

STICK FORWARD MEANS SPEED UP RATE 

STICK BACK MEANS SLOW METRONOME RATE 

NEVER GO BELOW ZERO 

OR ABOVE 255 

PRINT BEATS/MINUTE 
n 

LOACTION $0000 HOLDS THE RATE FOR 
THE FOLLOWING ASSEMBLY ROUTINE 



40 *=$600 

50 ; METRONOME ROUTI NE. . .USES $0000 PASS THE METRONOME RATE 



70 AUDF1 




$D200 AUDIO FREQUENCY REGISTER 


80 AUDC1 




$D201 AUDIO CONTROL REGISTER 


90 FREQ 




$08 AUDF1 VALUE 


0100 VOLUME 




$AF AUDC1 VALUE 


0110 OFF 




$A0 TURN OFF VOLUME 


0120 SETVBV 




$E45C SET TIMER VALUE ROUTINE 


0130 XITVBV 




$E462 


0140 CDTMV2 




$021 A TIMER 2 


0150 CDTMA2 




$0228 TIMER 2 VECTOR 


0160 ZTIMER 




$0000 ZPAGE VBLANK TIMER VALUE 


0170 ; 






0180 START 


LDA 


#10 


0190 


STA 


ZTIMER 

♦ 


0200 I NIT 






0210 ; SET THE TIMER VECTOR 


0220 ; 






0230 


LDA 


#CNTI NT&255 


0240 


STA 


CDTMA2 


0250 


LDA 


#CNTI NT/ 256 


0260 


STA 


CDTMA2+1 


0270 ; 






0280 ; SET THE TIMER VALUE AFTER THE VECTOR 


0290 ; 






0300 


LDY 


ZTIMER SET TIMER TWO TO COUNT 


0310 


JSR 


SET 1 ME 


0320 


RTS 
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0340 ; METRONME COUNT DOWN VECTORS TO HERE 

0350 ; 
0360 CNTINT 
0370 ; 

0380 ; SET UP AUDIO CHANNEL FOR MET CLICK 

0390 ; 



0400 


LDA 


#VOLUME 


0410 


STA 


AUDC1 


0420 


LDA 


#FREQ 


0430 


STA 


AUDF1 


0433 


LDY 


#$FF 


0437 DELAY 






0440 


DEY 




0442 


BNE 


DELAY 


0450 


STY 


AUDC1 


0460 


JMP 


INIT 



DELAY 



0470 ; 
0480 ; 
0490 ; 
0500 ; 
0510 SET I ME 
0520 
0530 
0540 
0550 
0560 
0570 
0580 



SUBROUTINE TO SET TIMER 



LDX 
LDA 
JSR 
RTS 

*=$2E2 

.WORD 

.END 



#0 
#2 

SETVBV 



START 



NO TIME >256 VBLANKS 
SET TIMER 2 

SYSTEM ROUTINE TO SET TIMER 



FIGURE 8.14 - - METRONOME 
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System timers 1-5 are two byte counters. They may be set to a value 
using the SETVBV routine. The O.S. then decrements them during VBLANK. 
Timer 1 Is decremented during Immediate VBLANK, Stage 1. Timers 2-5 are 
decremented during Immediate VBLANK, Stage 2. Different actions are taken by 
the O.S when the different timers are decremented to 0. 

System timers 1 and 2 have vectors associated with them. When timer 1 
or 2 reaches 0, the O.S. simulates a JSR thru the vector for the given timer. 
Figure 8.9B gives the vectors for the two timers. 

System timers 3-5 have flags that are normally SET (I.e. non-zero) . 
When either of the three timers count to 0, the O.S. will clear (zero) that 
timer's flag. The user may then test the flag and take appropriate action. 

Timers 1-5 are general purpose software timers that may be used for a 
variety of applications. For example, timer 1 Is used by SIO to time serial 
bus operations. If the timer counts to zero before a bus operation Is 
complete, a 'timeout f error Is returned. Timer 1 Is set to various values 
depending on the device being accessed. This Insures that, while a device 
has ample time to answer an I/O request, the computer will not f hang-up f 
indeflnltly waiting for a non-existant device to respond. Timer 3 Is also 
used by the O.S. The cassette handler uses timer 3 to set the length of time 
to read and write tape headers. Example 8.14 uses timer 2 to output a sound 
used as a metronome. The metronome's rate can be set to various values by 
using a joystick. 
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CHAPTER 9 
THE DISK OPERATING SYSTEM 



INTRODUCTION 

The Disk Operating System (DOS) Is an extension of the O.S. that allows 
you to access disk drive mass storage as files. You can access disk files 
Just like other files. Let's discuss the parts of DOS, then we will discuss 
how to use DOS. 

The Disk Operating System (DOS) has three parts, the resident disk 
handler, the File Manager (FMS) and the Disk Utility Package (DUP). The 
resident disk handler Is the only part of DOS In the O.S. ROM. FMS and DUP 
are located on diskette and are loaded ( f booted 1 ) Into the computer on 
powei — up. 

THE RESIDENT DISK HANDLER 

The resident disk handler Is the simplest part of DOS. The disk handler 
does not conform to the normal CIO cal ling sequence as does the other Device 
Handlers. The relationship of the Disk Handler to the I/O subsystem Is shown 
In Figure 8.1 In section 8.2 of this book. 

From figure 8.1 we can see that the DCB Is the way to communicate to the 
Disk Handler. The calling sequence for the Disk Handler Is: 

; caller has set up DCB 
JSR DSKINV ; system routine vector to the resident disk handler 
BPL OKAY ; Branch If success, Y Reg. ■ 1 

;Else y reg. m error status (DCBSTA also has error) 

The disk handler supports five functions: 

FORMAT Issue a Format command to the Disk Controller. 

READ SECTOR Read a specified sector. 

WRITE SECTOR Write a specified sector. 

WRITE/ VERIFY SECTOR Write sector, check sector to see If written. 
STATUS Ask the disk controller for Its status. 



The FORMAT command clears all the tracks on the diskette and the sector 
addresses are written on the tracks. No file structure Is put on the 
diskette by this command. 

The three sector I/O commands can be used to read and write sectors on 
the diskette. You can use them to Implement your own file structure. 
Section 10 of the O.S. Manual has an example of using the disk handler to 
write a boot file. 

The STATUS function Is used to determine the status of the disk 
drlve(s). You can use the Status command for several purposes. Since the 
timeout for a Status command Is smaller then the other commands, you can use 
It to see If a specific disk drive Is connected. If the Disk Handler returns 
a device timeout error, you know the disk Is not connected. 
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DUP 



DUP (Disk Utility Package) Is a set of utilities for diskettes, 
familiarly seen as the DOS menu. DUP executes commands by calling FMS 
through CIO. The commands are: 



FMS (File Management System) Is a non-resident device handler that uses 
the normal device handler-CIO Interface. FMS Is not present In the O.S. ROM. 
It Is booted In at power-up If a diskette containing DOS Is present. 

FMS, like the other device handlers, gets I/O control data from CIO. 
FMS then uses the resident disk handler to do I/O to the diskette. FMS Is 
called by setting up an IOCB and calling CIO. FMS supports some special CIO 
functions not available to other handlers: 

FORMAT FMS calls the resident Disk Handler to format the diskette. 

After a succesfull format, FMS writes some file structure 

data on the diskette. 
NOTE FMS returns the current file pointer. 
POINT FMS sets the file pointer to a specified value. 



You can access ail the standard file I/O calls through CIO. In BASIC 
this means using the I/O commands, such as OPEN, CLOSE, GET, PUT. In 
assembly language you have to set up the IOCB yourself and call CIO. Let's 
use BASIC to provide an easy Introduction to DOS. 



A. 
B. 
C. 
D. 
E. 
F. 
G. 
H. 
I . 
J. 
K. 
L. 
M. 
N. 
0. 



D I RECTORY 
RUN CARTRIDGE 
COPY FILES 
DELETE FILES 
RENAME FILES 
LOCK FILES 
UNLOCK FILES 
WRITE DOS FILES 
FORMAT DISK 
DUPLICATE DISK 
SAVE BINARY FILE 
LOAD BINARY FILE 
RUN AT ADDRESS 
WRITE MEM.SAV FILE 
DUPLICATE FILE 



FMS 



DISK I/O 
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To do any disk I/O, you must first OPEN a file. The BASIC syntax for 
the OPEN Is: 

OPEN # I OCB , I CAX 1 , 0 , "D : MYPROG . BAS ff 

The #IOCB selects one of the 7 lOCBs avallalble from BASIC (BASIC Itself 
uses IOCB #0). ICAX1 Is the OPEN type code. The bits for the type code are: 

BIT 7 6 5 5 3 2 1 0 
xxxxWRD A 



Where: A Is Append 

D Is Directory 
R Is Read 
W Is Write 
x Is unused 

The various values for ICAX1 are discussed In section 5 of the O.S. Manual 
Some of the key things to note about the various OPEN modes are: 



I CAX 1=6 

I CAX 1=4 
I CAX 1=8 

I CAX 1=9 

ICAX1=12 

ICAX1=13 



This Is used to OPEN the diskette directory. Records READ 
are the diskette directory entries. 
READ mode. 

WRITE mode. Any file 0PEN f ed In this mode Is deleted. The 

first bytes written will be at the start of the file. 

WRITE APPEND mode. The file Is left Intact. Bytes written 

to this file are put at the end of the file. 

UPDATE mode. This mode allows both READ and WRITE to the 

file. Bytes READ/WR I TE 1 en start at the first byte In the 

file. 

Not supported. 



Now that we know how to OPEN a file, let's see how to transfer data 
between our program and the disk. There are two types of I/O you can use, 
record or character. 

Character I/O simply means that the data In a file Is one list of bytes. 
DOS Interprets this list of bytes as data (no Imbedded control characters). 
This Is an example of character data (all values hex): 00 23 4F 55 FF 34 21. 

Record I/O means that data In a file Is made up of a set of records. A 
record Is a group of bytes delimited by an EOL ($9B). This Is an example of 
two records: 

00 23 4F 55 FF 34 9B 21 34 44 9B 
I record 1 ! record 2 ! 
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Record and character I/O to files can be done in any arbitrary order. 
As a matter of fact, data created as records can be read as characters. File 
data created as characters can be read as records. The only difference 
between character and record I/O Is that records end with $9B. $9B Is 
treated as ordtnary data when using character I/O. 

BASIC supports record I/O quite well. The commands PRINT and INPUT can 
be used to write and read records from files. BASIC does not support 
character I/O as well as It could. The commands GET and PUT allow you to 
read and write a single byte at a time. 

The O.S. has the ability to read and write blocks of characters. This 
ability Is not used by BASIC. Besides the length of the block, the O.S. 
allows you to specify the address of the block. To use the character block 
mode of the O.S. from BASIC, you can write an Assembly language module to be 
called from BASIC by the USR function. Figure 8.6 In section 8.2 of this 
book has an example of a subroutine to do character block I/O. 



RANDOM ACCESS 

One of the most Important uses of the diskette Is for random access of 
stored records In an arbitrary order. Using the I/O commands In conjunction 
with the special commands NOTE and POINT allows the creation and use of 
random access f 1 1 es . 

NOTE and POINT read and update the file pointer respectively. DOS keeps 
a file pointer for each file currenty OPEN which tells the DOS the current 
location In the file. The file pointer has two parameters, the sector number 
and the byte count. The sector number (a value from 1-719) tells the DOS 
what sector on the diskette the file pointer Is pointing to. The byte count 
Is a count Into the sector we are on (e.g. the first byte In a sector has a 
byte count of 0, the second byte Is one, etc.). Figure 9.1 shows the 
relationship of the file pointer to the file. All values are hex. The file 
pointer values for the bytes In this file are given below the bytes In the 
file. 
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E E E 

0 0 0 

A B CLDEFLGH I JkL AB 

File 41 42 43 9B 44 45 46 9B 47 48 49 4A 4B 9B...41 42 

File Pointer 
S©c"for 

Number 50 50 50 50 50 50 50 50 50 50 50 50 50 50... 50 51 
Byte 

Count 0 1 23456789ABCD...7C0 

The above file was created In BASIC by: 
10 OPEN #1,8,0,»DzFILE" 
20 ?#1; f, ABC" 



30 ?#1;"DEF" 
40 ?#1; ft GHIJ ff 



:REM Fill the rest of the sector 



100 ?#1; ft AB lf :REM This writes a record that crosses end of sector 
150 CLOSE #1 

FIGURE 9.1 NOTE AND POINT VALUES 



The sector number Is 50 because DOS arbitrarily started this file on 
sector 50. The sector number changes to 51 because the file Is longer than a 
sector. DOS linked the file to the next available sector, 51. The record 
ff AB ff crosses the end of the first sector. 

The byte count of the file pointer starts at 0 and Is Incremented until 
the end of the sector, $7D (125 Dec). DOS reserves the last 3 bytes of 
every sector for overhead data for the file. For files on the 810, the 
maximum byte count Is 124 (0-124 = 125 total bytes). The maxlmun for the 815 
Is 252 (253 total bytes). When the file reaches the end of a sector, the 
Byte Count resets to 1 . 

You should now have a good Idea how records are stored on the diskette 
and how to retrelve them. Figure 9.2 Is a subroutine to save records, keep 
track of where they are, and retrieve them. Appendix VIII Is a complete 
random access method written In Basic. 
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1000 REM THIS ROUTINE CREATES AND ACCRESSES RANDOM ACCESS FILES FOR FIXED 
LENGTH RECORDS 

1001 REM COMMANDS ARE 

1002 REM CMD=1 WRITE NTH RECORD 

1003 REM CMD=2 READ NTH RECORD 

1004 REM CMD=3 UPDATE NTH RECORD 

1005 REM 

1006 REM RECORDS IS THE I NPUT/OUTPU RECORD 

1007 REM N IS THE RECORD NUMBER 

1010 REM INDEX IS A TWO D I MENS I NAL ARRY DIM»ED I NDEX( 1 ,RECNUM) . INDEX HOLDS 

THE NOTE VALUES FOR ALL RECORDS 

1020 REM I0CB1 IS THE ASSUMED DATA FILE 

1100 REM 

1200 ON CMD GOTO 2000,3000,4000 
2000 REM 

2100 REM WRITE NTH RECORD 
2200 NOTE #1,X,Y 

2300 INDEX(SEC,N)=X:INDEX(BYTE,N)=Y 
2400 ? # 1 ; RECORDS : RETURN 
3000 REM 

3010 REM READ NTH RECORD 
3020 REM 

3030 X=INDEX(SEC,N):Y=INDEX(BYTE,N) 
3040 POINT #1,X,Y 
3050 INPUT #1; RECORDS 
3060 RETURN 
4000 REM 

4010 REM UPDATE NTH RECORD 
4020 REM 

404U X=INDEX(SEC,N):Y=INDEX(BYTE,N) 
4050 POINT #1,X,Y 
4060 ? #1; RECORDS 
4070 RETURN 



FIGURE 9.2 NOTE AND POINT EXAMPLE 
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CHAPTER 10 
SOUND 



I. ATARI 400/800™ hardware capabilities 



The ATARI 400/800™ has extensive sound capabilities. There are 4 sound 
channels, Independently controllable. Each channel has a frequency register 
determining the note, and a control register regulating the volume and the 
noise content. Several options allow you to Insert hl-pass filters, choose 
clock bases, set alternate modes of operation, and modify poly-counters. 

For the purposes of this chapter, a few terms need to be clarified: 

1 hz (hertz) Is 1 pulse per second 

1 Khz (kilo-hertz) Is 1,000 pulses per second 

1 Mhz (mega-hertz) Is 1,000,000 pulses per second 

A pulse Is henceforth defined to be a sudden voltage rise followed by a 
sudden voltage drop, Internal to an electronic circuit, which, if sent to the 
TV speaker, will be turned into an audible pop (several In succession will be 
a buzz, etc.) . 

A "wave" as used here refers to a voltage change with respect to time, 
and also denotes a type of sound; I.e., waves created by the ATARI 400/800™ 
are square waves (like In figure 10.2), brass instruments produce triangle 
waves, and a singer produces sine waves (depicted In figure 10.15). If sent 
to the TV speaker, this voltage wave will be converted to a sound wave. 

A single square wave Is the same as a pulse as described above, and a 
continuous string of pulses Is a square wave. 

A shift register Is like a memory byte (In that It holds binary data) 
that when Instructed, shifts all Its bits to the right one position; I.e., 
bit 5 will get whatever was In bit 4, bit 4 will get whatever was In bit 3, 
etc. Thus, the right-most bit is pushed out, and the left-most bit assumes 
the value on Its Input wire: 



before shift: 



^ input 



after shift 



1 


2 


3 


4 


5 




A 


















1 


2 


3 


4 


5 



UtPUt 



figure 10.1 
diagram of bit flow of a shift register 



AUDF1-4 Is to be read, "any of the audio frequency registers, 1 through 
4." Their addresses are: $D200, $D202, $D204, $D206 (53760, 53762, 53764, 

53766) . 

AUDC1-4 Is to be read, "any of the audio control registers, 1 through 
4." Their addresses are: $0201, $D203, $D205, $D207 (53761, 53763, 53765, 

53767 ) . 

The words "frequency", "note", "tone", and "pitch" are used 
Interchangeably. Their meanings are Identical for the purposes of this 
chapter. 

"Noise" and "distortion" are used Interchangeably although their 
meanings are not the same. "Noise" Is a more accurate description of the 
function performed by the ATARI 400/800™. 

The 60 hz Interrupt referred to In part II of this chapter Is also 
called the vertical blank Interrupt. 

All examples are In BASIC unless otherwise stated. Type the examples 
exactly as they appear; I.e., If there are no line numbers, don f t use any, 
and If several statements are on the same line, type them as such. 

You will encounter some problems when POKEIng sounds In BASIC or In 
machine language. The POKEY chip needs to be Initialized before It will work 
properly. To Initialize In BASIC, do a null sound statement; I.e., SOUND 
0,0,0,0. In machine language, store a 0 at AUDCTL ($D208 = 53768), and a 3 
at SKCTL ($D20F = 53775). 
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AUDF1-4 

Each audio channel has a corresponding frequency register which controls 
the note played by the computer. 

The frequency register contains the number f N f used In a divide by N 
circuit. This divide Is not a division In the mathematical sense, but rather 
something much simpler: for every N pulses coming In, 1 pulse goes out. For 
example, below Is a diagram of a divide by 4 function: 



Input 
pul 



« 

r 
t 



: 
s 

I 



output 
pu I ses 



— — i 



figure 10.2 
divide by 4 diagram 



As N gets larger, output pulses will become less frequent, making a 
lower note. 

For the purposes of this discussion, frequency Is a measure of the 
number of pulses In a given amount of time; I.e., a note with a frequency of 
100 hz means that in one second, exactly 100 pulses will occur. The more 
frequent (hence the term "frequency") the pulses of a note, the higher the 
note. For example, a soprano singer sings at a high frequency (perhaps 5 
Khz), and a cow moo's at a low frequency (perhaps 100 hz). 



AUDC1 -4 

Each channel also has a corresponding control register. These registers 
allow the volume and distortion content of each channel to be set. The bit 
assignment for AUDC1-4 Is as follows: 
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5 



AUDC1 -4 



bit number 


7 


6 


5 


4 


3 


2 


1 


0 




d I stort i on 


vol 
on ly 


vo 1 ume 



figure 10.3 
AUDC1-4 bit assignment 



VOLUME: The volume control for each audio channel Is very 
straightforward. The lower 4 bits of the audio control registers represent a 
4 bit number that corresponds to a volume level. A zero In these bits means 
no volume, and a 15 means as loud as possible (there are 16 volume levels). 

The sum of the volumes of the 4 channels should not exceed 32, since 
this forces overmodul atlon of the audio output. The sound produced tends to 
actually lose volume and assume a buzzing quality. 



DISTORTION: Each channel also has 3 distortion control bits In Its 
audio control register. Distortion Is used to create special sound effects 
any time a pure tone Is undeslreable. 

Atari f s use of distortion Is unique In the Industry. Its versatility 
and controllability lend It well to the synthesis of an almost endless 
variety of sounds, from rumbles, rattles, and squawks to clicks, whispers, 
and mood setting background tempos from lurking ghost I es or from outer space. 

Distortion as defined by Atari Is not equivalent to the standard 
Interpretation. For example, "Intermodulatlon distortion" and "harmonic 
distortion" are quality criteria specified for high fidelity stereo systems. 
These types of distortion refer to waveform degeneration, where the shape of 
the wave Is slightly changed due to error In the electronic circuitry. 
Atari f s distortion does not alter waves (they are always square waves), but 
rather deletes selected pulses from the waveform. This technique Is not 
adequately characterized by the word "distortion". A more descriptive and 
appropriate term for Atari f s distortion methods Is "noise". 

But before Atari f s noise generation techniques can be fully grasped, you 
must understand poly counters. 

Poly counters are employed In the ATARI 400/800'" as a source of random 
pulses used In noise generation. Atari's poly counters consist mostly of a 
shift register (see description of shift register at the beginning of the 
chapter) made to shift rapidly (1.79 Mhz). The shift register's output 
delivers the random pulses, and Its Input Is determined by processing the 
values of selected shift register bits. 
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For example, In the diagram below, the old value of bit 5 will be pushed 
out of the shift register to become the next random pulse, and bit 1 will 
become a function of bits 3 and 5: 




figure 10.4 
5 bit poly-counter 



The bit processor gets values from certain bits In the shift register 
(bits 3 and 5 above), and processes them In a way Irrelevant to this 
discussion. It yields a value which Is used to become bit #1 of the poly 
counter's shift register. 

These poly counters are not truly random since they repeat their bit 
sequence after a certain span of time. As you might suspect, their 
repetition rate depends upon the length (the number of bits long) of the 
shift register used In the poly counter; I.e., the longer ones require many 
shifts before they repeat, while the shorter ones repeat more often. 

With some background In poly counters, you are now equipped to 
understand how Atari generates distortion. 

On the ATARI 400/800™, distortion Is achieved by using random pulses 
from these poly counters In a selection circuit. This circuit Is actually a 
digital comparator, but "selection circuit" Is more descriptive and thus will 
used In this chapter. 

The only pulses making It through the selection circuit to the output 
are ones coinciding with a random pulse. Various pulses from the Input are 
thereby eliminated In a random fashion. The following Illustrates this 
selection method. A dotted line connects pulses that coincided: 




i i : i i : s : J 

i r ? ? ! i f 

pulses that 
make It thru 



figure 10.5 
selection type function 
used to mix In distortion 



The net effect Is this: some pulses from the frequency divide by 
circuit (discussed part I, section entitled AUDF1-4) are deleted. Obviously, 
If various pulses are deleted, the note will sound different. This Is how 
distortion Is Introduced Into a sound channel. 

Since poly counters repeat their bit sequences, a pattern of pulses will 
be repeated. And since the selection circuit uses this pattern to delete 
pulses, the distorted note will be similarly patterned. It Is this method 
which allows the programmer to create noises such as drones, motors, and 
other sounds having repetitive patterns. 

The ATARI 400/800™ Is equipped with three poly counters of different 
lengths, providing several levels of randomness. The smaller poly counters 
(4 and 5 bits long) repeat often enough to create droning sounds that rise 
and fall quickly, while the larger poly counter (17 bits long) takes so long 
to repeat that no pattern to the distortion Is readily apparent. This 17 bit 
poly counter can be used for explosions, steam, and any sound where random 
crackling and popping Is desired. It Is even Irregular enough to be used to 
generate white noise (an audio term meaning a hissing sound). For an example 
of white noise generation, try the following: 



SOUND 0,100,8,8 
POKE 53768,64 



A 9 bit poly counter option offers a reasonable compromise between the 
short poly counters and the long one (see part I, discussion of AUDCTL). 
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Each audio channel offers 6 distinct combinations of the three poly 
counters: 



AUDC1 -4 



17 6 .514131211101 


* 1 I 




0 0 0 


dfv clock 


0 X 1 


dlv clock 


0 1 0 


dlv clock 


1 0 0 


dlv clock 


1 X 1 


dfv clock 


1 1 0 


dlv clock 



NOTES: "Clock" means the base frequency - 
discussion, part I . 



AUDCTL 



An f X f means, "It doesn f t matter If this bit Is set or 
not." The structure of AUDC1-4 as shown In figure 10.7 will 
clarify why It doesn't matter. 



figure 10.6 
available poly counter combinations 



These upper AUDC1-4 bits control three switches In the audio circuit as 
shown below. This diagram will help you understand why the table of figure 
10.6 Is structured as It Is: 



AUDCTL bit no. 6 "7 



4 bit poly 



17 bit poly 



5 bit poly 



input 
from ^ 
div. by 



J 



selection 
circuit 




circuit 




figure 10.7 
AUDC1-4 block diagram 



Each combination of the poly counters offers a unique sound. When 
striving for a particular sound, try each poly counter combination at 
several frequencies since one distortion setting can sound completely 
different at different frequencies. Below Is a table of suppositions, just 
to get you started: 



AUDC1-4 



17I6I5I4I5I211 101 



0 


0 


0 


0 


X 


1 


0 


1 


0 


1 


0 
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1 
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1 


1 


1 
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>w frequencies middle frequencies high frequencies 

gelger counter raging fire rushing air steam 

machine gun auto at idle electric motor power transformer 
calm fire laboring auto auto with a "miss" 

building crashing In radio Interference waterfall 

pure tones 

alrpl ane I awn mower electric razor 



figure 10.8 
sounds produced by distortion combinations 

at several frequencies 
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Summary of distortion: A shift register Is used as the main component 
of a poly counter, which Is used to generate random pulses. The random 
pulses are used to delete selected note pulses, thereby Introducing 
distortion Into a channel. The upper bits (bits 7,6,5) of AUDC1-4 toggle 3 
switches which select the poly counters to be used In that channel for 
distortion. 

VOLUME ONLY: Bit #4 of AUDC1-4 specifies a volume only mode. When 
this bit Is set, the volume bits (AUDC1-4 bits 0-3) are sent to the TV as 
volume; I.e., no frequency is associated with this bit. 

To fully understand the use of this mode of operation, you must 
understand how a speaker works and what happens to the TV speaker when it 
receives a pulse. 

Any speaker has a cone which moves In and out. The cone f s position at 
any time Is directly proportional to the voltage It Is receiving from the 
computer at that time; i.e., If the voltage sent Is zero, then the speaker 
Is In the resting position, and If the voltage sent Is 5, then the speaker 
Is In the extended position. And whenever the cone changes position, It 
moves air which Is detected by your ear as sound. 

From our definition of a pulse, you know that it consists of a rising 
voltage followed by a falling voltage. If we were to send the speaker a 
pulse, It would push out with the rising voltage, and pull back with the 
falling voltage, resulting In a wave of air which can be detected by your 
ear as a pop. The following statements will produce such a pop on the TV 
speaker by sending a single pulse: 

POKE 53761 ,31 :P0KE 53761,16 



A stream of pulses (or wave) would set the speaker Into constant 
motion, and a continuous buzz would be heard. This Is how the computer 
generates sound on the TV speaker. 

It is essential to note that the volume sent does not drop back to 
zero, but rather remains until the program changes It. The program Is 
expected to modulate the volume often enough to create a noise. Now try the 
following, listening carefully after each statement: 



POKE 53761,31 
POKE 53761,31 



The first time you heard a pop, which is as expected; I.e., the speaker 



pushed out and moved air. But the second time you didn't. This Is because 
the speaker cone Is already In the extended position - another extension 
command does nothing to the speaker, moving no air, so you hear nothing. 
Now try this: 



POKE 53761,16 
POKE 53761,16 



Just like before, you heard a pop the first time as the speaker moved 
back to Its resting position, and you heard nothing the second time since 
the speaker was already In the resting position. 

Thus, the volume only bit allows the program complete control over the 
position of the speaker at any time. Although the examples given above are 
only binary examples (either all on or all off), you are by no means limited 
to this type of speaker modulation. You are actually aHowed to force the 
speaker to any of 16 distinct positions. 

For example, a simple triangle wave (similar to the waveform produced 
by brass Instruments) could be generated by sending a volume of 8 followed 
by 9, 10, 11, 10, 9, 8, 7, 6, 5, 6, 7, and back to 8, and repeating this 
sequence over and over very rapidly (BASIC Is too slow). In this example, 7 
of the possible 16 speaker positions are used. (The sample program given 
under the machine code sound generation section would In fact make a 
triangle wave If Its duration table contained all 1 f s). 

Therefore, by changing the volume quickly virtually any waveform can be 
created. It Is feasible, for example, to make the computer say, "Hello" In 
a clear voice. 

If you have never been exposed to wave theory, audio, or electronics, 
the purpose and use of the volume only bit will seem very convoluted. It 
would probably be best In this case to buy a book on the subject. 

There Is a continued discussion of this bit In part II. 



AUDCTL 

In addition to the Independent channel control bytes (AUDC1-4), there 
Is an option byte (AUDCTL) affecting all the channels. Each bit In AUDCTL 
Is assigned a specific function: 
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AUDCTL ($D208 = 53768) 



If set, this bit... 



17I6I5I4I3I2 



E3 



^switches main clock base from 64 Khz to 15 Khz 
-Hnserts high-pass filter Into chan 2, clocked by chan 4 
inserts high-pass filter Into chan 1, clocked by chan 3 
joins channel 4 to channel 3 (16 bit resolution) 
joins channel 2 to channel 1 (16 bit resolution) 
■^clocks channel 3 with 1.79 Mhz 
-*c locks channel 1 with 1.79 Mhz 
-^makes the 17 bit poly counter Into a 9 



poly 



figure 10.9 
AUDCTL bit assignment 



CLOCK I NG: Before proceeding with the explanations of the AUDCTL 
options, clocking must be well understood. In general, a clock Is a train 
of pulses used to synchronize the millions of minute Internal operations 
occurring every second In any computer. A clock pulses continuously, each 
pulse telling the circuitry to perform another step In Its operation. 

The section on frequency explained that a frequency divider outputs 
only every Nth Input pulse. But where do the Input pulses come from? The 
clock! 

Several clocks are used In the computer, and AUDCTL allows you to 
change the clock used as the Input to the divide by N to either a faster or 
a slower clock. When this Input clock changes, the output from the 
frequency divide by changes proportionally. 

For example, Imagine the clock to be pulsing at a rate of 15 Khz, and 
the frequency register Is set to divide by 5. The rate of output pulses 
from the divide by circuit would be 3 Khz. But If we changed the clock, or 
Input frequency, to 40 Khz without changing the frequency register, then 
what would happen? The divide by N would still be outputtlng every 5th 
pulse, but It Is receiving Input at a faster rate, and thus every 5th pulse 
comes along sooner. The result Is an output frequency (from the divide by 
N) of 8 Khz. 

The formula for the output frequency (from the divide by N) Is quite 
simple: 

clock 

output frequency = 

N 



This shows that the output 
Input clock. 



frequency Is directly proportional 



to the 



So, If someone were to make the clock speed up, then everything using 
that clock would execute with less delay. In the case of the ATARI 400/800™ 
audio circuitry, If the clock rate was Increased, then every sound pulse to 
the TV would be packed closer together, making a higher frequency, or tone 
(see part I, section on frequency). 

The Inverse Is true as well - If the clock Is slowed, all pulses would 
spread out, lowering the frequency. 

15 Khz OPTION: Try the following: 



As explained In the section on clocking, a slower clock produces a less 
frequent string of output pulses, or a lower sound. Location 53768 Is 
AUDCTL, and a 1 sets bit #0, which switches the 64 Khz clock Into a 15 Khz 
clock. In the above demonstration, you heard the frequency drop to about 
1/4th the original frequency, since the clock dropped to 1/4th its original 
rate. 

It Is important to note that if this bit Is set, every sound channel 
clocked off 64 Khz will be changed to the 15 Khz clock base. 



1.79 Mhz OPTIONS: Try the following: 



SOUND 0,255,10,8 turn on channel #1, low tone 

POKE 53768,64 * set AUDCTL bit #6 



As explained In section on clocking, changing the time base 
proportionally changes the frequency heard. In this case, putting a 64 Into 
AUDCTL causes channel #1 to use the 1.79 Mhz time base rather than the 64 
Khz time base. As you might have expected from the previous section, the 
POKE caused the tone to become higher. The change made a substantial 
difference since 1.79 Mhz Is almost 30 times faster than 64 Khz. 

Setting AUDCTL bit #5 forces channel #3 to use 1.79 Mhz as Its clock in 
the same manner: 



SOUND 0,128,10,8 
POKE 53768,1 



AUDCTL 15 Khz option 



medium tone 



SOUND 2,255,10,8 
POKE 53768,32 



turn on channel #3, low tone 
set AUDCTL bit #5 
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These options extend the range of the frequencies capable of being 
generated to well beyond the limits of the human ear (we can hear up to 
about 20 Khz). 

16 BIT OPTIONS: AUDCTL bits 3 and 4 allow two channels to be joined, 
creating a single channel with an extended dynamic range* Working 
Independently, each channel's frequency can range from 0 to 255 (8 bits of 
divide by N capability). Joining two channels allows a frequency range of 0 
to 65535 (16 bits of divide by N capability). In this mode It Is possible 
to reduce the output frequency to single pops separated by several seconds. 
The following program uses two channels In the 16 bit mode, and two paddles 
as the frequency Inputs. Insert a set of paddles Into port #1, type In and 
run the following program: 

10 SOUND 0,0,0,0 Initialize sound 

20 POKE 53768,80 clock ch1 w 1.79 Mhz, clock ch2 w ch1 

30 POKE 5376 1,1 60: POKE 53763,168 turn off ch1, turn on ch2 (pure tones) 
40 POKE 53760,PADDLE(0):POKE 53762, PADDLE( 1 ) 

50 GOTO 40 use paddles to put freqs In freq regs 



The right paddle tunes the sound coarsely, and the left paddle finely 
tunes the sound between the coarse Increments. 

This program first sets bits 4 and 6 of AUDCTL which means, "clock 
channel #1 with 1.79 Mhz, and join channel #2 to channel #1." Once this 
happens, the 8 bit frequency registers of both channels are assumed to 
represent a single 16 bit number N, used to divide the Input clock. 

Next, channel #1 f s volume Is set to zero. This Is because the output 
from channel #1 Is meaningless to anything but channel #2. When these 
channels are put Into their 16 bit mode, Internal changes cause the two 
channels to act as one 16 bit divide by N. These changes Invalidate the 
output of the first channel. 

Channel #1 f s frequency register Is used as the fine or low byte In the 
sound generation, and channel #2 f s frequency register Is the coarse or high 
byte. For example, POKEIng a 1 Into channel #1 f s frequency register makes 
the pair divide by 1. POKEIng a 1 Into channel #2 f s frequency register 
makes the pair divide by 256. And POKEIng a 1 Into both frequency registers 
makes the pair divide by 257. 

Bit #3 of AUDCTL can be used to join channel #4 to channel #3 In 
precisely the same way. 

The 16 bit option Is useful In applications where a finer control over 
the frequency is desired. These finer Increments are achieved by making the 
Input clock 1.79 Mhz, and using one of the 16 bit options as in the above 
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program, 1 1 ne 20. 



To understand why the Increments are finer, you must understand what 
happens to the output frequency as the value In the frequency register 
changes. First a concrete example: If the frequency register Is dividing 
by one, and the Input frequency Is 1 Khz, the output Is 1 Khz. Now 
Increment the frequency register so that It Is dividing by 2, and we get an 
output of 500 hz, which Is a drop of 500 hz. Increment the frequency 
register once more so that It Is divides by 3, and the output becomes 333 
hz, a drop of 267 hz. The second Increment had less effect than the first 
(the first Increment affected a change of 500 hz, while the second Increment 
affected only a 267 hz change). If we were to Increment further, each step 
would continue to have less effect than Its predecessor. 

The Idea Is basically this: the larger the number N In the frequency 
divide by register, the smaller the difference In output frequency as N 
changes. 

Therefore, while clocking the 16 bit channel with 1.79 Mhz then 
dividing by several thousand will yield the same output frequency as an 8 
bit channel clocked with 64 Khz and dividing by several hundred, the 16 bit 
channel will offer finer resolution since each Increment (or decrement) 
causes less effect. 

For a little 16 bit variety try the following statements, and 
experiment with various value combinations In the last 4 POKEs: 



SOUND 0,0,0,0 f % /UfDCTl. 

POKE 53768,24 P2<>*< •» 

POKE 53761 ,168 

POKE 53763,168 

POKE 53765,168 

POKE 53767,168 \/lol ^ f VlO^L^O 
POKE 53760,240: REM try POKE I ng other numbers Into these next 4 locations 
POKE 53764,252 D20*< F< \ fcaOf- tMLfct*. 




POKE 53762,28 VM>} f *C 
POKE 53766,49 V* * *A ' 



HIGH-PASS FILTERS: AUDCTL bits 1 and 2 control high pass filters In 
channels 2 and 1 respectively. A high-pass filter Is Indeed a filter In 
that It allows only selected things to pass through. As the name Implies, 
the things allowed to pass are high frequencies. 

In the case of these high-pass filters, high frequencies are defined to 
be anything higher than the clock. The clock In this case Is the output of 
some other channel. 

For example, If channel #3 Is playing a cow's moo, and AUDCTL bit #2 Is 
set, then only a noise or sound with a frequency higher than the moo will be 
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heard on channel #1 (anything lower than the "moooo 11 will be filtered out): 




cow's moo (played by channel #3) 



channel #1 
will only pi ay 
frequencies In 
this shaded area 



time 



figure 10.10 
diagram of the effect of a high-pass filter 
Inserted In channel #1 and clocked by channel #3 



r 



The filter Is programmable In real time since the clock used Is 
actually another channel which can be changed on the fly. This opens a 
large field of possibilities to the programmer. 

The filters are used mostly to create special effects. Try the 
fo I lowing: 

SOUND 0,0,0,0 ' , ,» 

POKE 53768,4 1)20*0+ S 

POKE 53761 ,168: POKE 53765,168 
POKE 53760, 254: POKE 53764,127 

9 BIT POLY CONVERSION: Bit #7 of AUDCTL turns the 17 bit poly counter 
Into a 9 bit poly counter. The discussion of poly counters explained that 
the shorter the poly counter, the more often Its distortion repeats, or the 
more dlscernable the pattern In the distortion. Therefore, It Is reasonable 
to assume that changing the 17 bit poly Into a 9 bit poly will make the 
noise pattern more dlscernable. 

Try the following demonstration of the 9 bit poly option, listening 
carefully when the POKE Is executed: 
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SOUND 0,80,8,8 
POKE 53768,128 



use the 17 bit poly 
change to the 9 bit poly 
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II. Sound Generation Software Techniques 



There are two basic ways to use the ATARI 400/800™ sound system: 
static and dynamic. Static means that the program sets a few sound 
generators, waits, then turns them off. Dynamic means that the sound 
generators are continuously updated as the program Is executing. For 
example: 



static sound dynamic sound 

SOUND 0,120,8,8 FOR X=0 TO 255 

SOUND 0,X,8,8 
NEXT X 



Static sound 

Static sound Is quite limited. Mostly, the only sounds that can be 
made are beeps, clicks, and buzzes. However, there are a few exceptions to 
this rule. Two examples are the programs given as special effects In part 
I, sections on high-pass filters, and 16 bit sound. Another simpler example 
Is using two sound channels In the following way: 



SOUND 0,255,10,8 

SOUND 1,254,10,8 <rh» 



The strange effect Is a result of closely phased peaks and valleys. 
Examine the diagram below. It shows two channels Independently running sine 
waves at slightly different frequencies, and their sum. The sum curve shows 
the strange Interference pattern created when these two channels are added. 



ch- 1 



ch. 2 



ch. 1 
+ 

ch. 2 




• 



figure 10.11 
two sine waves at different frequencies, 

and their sum 
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Before the sound channels are sent to the TV they are mixed together. 
The mixing process Is similar to the mixing performed by the human ear; a 
simple addition. 

Figure 10.11 shows that at some points In time the waves are assisting 
each other, and at other points, they are In direct conflict. Adding the 
volumes of two waves whose peaks have coincided will yield a wave with twice 
the strength, or volume. Likewise adding the volumes of two waves while one 
Is peaking and the other Is at a low will result In a cancellation of both 
of them. 

On the graph of the sum curve, we can see this In action. Toward the 
ends of the graph, volume Increases since both channels 1 peaks and valleys 
are close together, almost doubling the sound. And toward the middle of the 
graph the waves oppose each other and the resulting wave Is flat. An 
Interesting project might be writing a program to plot Interaction patterns 
of 2, 3, and 4 channels like In figure 10.11. You could possibly discover 
some very unique sounds. 

The more slight the difference In frequency between the two channels, 
the longer the pattern. To understand this, draw yourself some graphs 
similar to figure 10.11 and study the Interaction. As an example, try the 
following statements: 



SOUND 0,255,10,8 
SOUND 1,254,10,8 
SOUND 1,253,10,8 
SOUND 1,252,10,8 



There are many other similar examples, using the same principle: 



SOUND 0,254,10,8 
SOUND 1,127,10,8 



Dynamic sound 

In general, any sound that Is not a simple beep, click or buzz must be 
generated using dynamic sound. Three levels of dynamic sound are available 
to the ATARI 400/800™ programmer: sound In BASIC, 60 hz Interrupt, and sound 
In machine code. 



BASIC SOUND: BASIC is somewhat limited in Its sound capabilities. As 
you may have noticed, any SOUND statement kills any modified AUDCTL setting. 



This potential problem can be avoided by POKEIng In sounds rather than 
using the SOUND statement. The sample program given In part I under 
AUDCTL's 16 bit options Is a good example of such a technique. 

In addition, BASIC Is I Imltted on account of Its speed. If the program 
Is not entirely dedicated to sound generation, there Is general ly not enough 
processor time to do more than static sound or choppy dynamic sound. The 
alternative Is to temporarily halt all other processing while generating 
sound. 

Another problem can occur when using the computer to play music on more 
than one channel. If all 4 channels are used, the time separation between 
the first sound statement and the fourth can be substantial enough to make a 
noticeably obnoxious delay between the melody and the harmony. 

The following is a solution to this dilemma: 



10 SOUND 0,0,0,0:DIM SIMUL$(16) 
20 RESTORE 9999 :X=1 

25 READ Q:IF Q<>-1 THEN S IMUL$(X)=CHR$(Q) :X=X+1 :G0T0 25 
27 RESTORE 100 

30 READ F1,C1,F2,C2,F3,C3,F4,C4 
40 IF F1=-1 THEN END 

50 X=USR(ADR(SIMUL$),F1,C1,F2,C2,F3,C3,F4,C4) 
55 FOR X=0 TO 150: NEXT X 
60 GOTO 30 

100 DATA 182,168,0,0,0,0,0,0 
110 DATA 162,168,182,166,0,0,0,0 
120 DATA 144,168,162,166,35,166,0,0 
130 DATA 128,168,144,166,40,166,35,166 
140 DATA 121,168,128,166,45,166,40,166 
150 DATA 108,168,121,166,47,166,45,166 
160 DATA 96,168,108,166,53,166,47,166 
170 DATA 91,168,96,166,60,166,53,166 
999 DATA -1,0,0,0,0,0,0,0 
9000 REM 
9010 REM 

9020 REM this data contains the machine lang. program, 
9030 REM and Is read Into SIMULS 

9999 DATA 104,133,203,162,0,104,104,157,0,210,232,228,203,208,246,96,-1 



In this program, SIMUL$ Is a tiny machine language program that "pokes" 
all four sound channels virtually simultaneously. Any program using SIMUL$ 
can accurately phase all four channels. 

Any program can call SIMULS by simply putting the sound register values 
inside the USR function as shown above In line 50. The parameters should be 
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ordered as shown, with the control register value following the frequency 
register value, and repeating this ordering 1 to 4 times, once for each 
sound channel to be set. 

As a speed consideration as well as a convenience, SIMULS allows you to 
specify sound for less than 4 channels; I.e., 1, 2, and 3 or 1 and 2, or 
just channel 1. Simply don f t put the unused parameters Inside the USR 
function. The following shows a SIMULS call with only the first 2 channels: 



X=USR(ADR(SIMUL$) ,F1 ,C1 ,F2,C2) 



SIMULS offers another distinct advantage to the BASIC programmer. As 
mentioned earlier, the AUDCTL register Is reset upon execution of any SOUND 
statement In BASIC. However, using SIMULS, no SOUND statements are 
executed, and thus the AUDCTL setting Is retained. 

There Is one other very Impractical method of sound generation In 
BASIC. This Is using the volume only bit of any of the four audio control 
registers. Type In and run the following: 



SOUND 0,0,0,0 

10 POKE 53761 ,16:P0KE 53761 ,31 :60T0 10 



This program sets the volume only bit In channel #1 and modulates the 
volume from 0 to 15 as fast as BASIC can. Practically speaking, this 
program uses 100? of the processing time available, and produces only a low 
buzz. 

The best way to get complex sounds In BASIC without sacrificing the 
entire processor is using the 60 hz Interrupt technique described In the 
next section. 



60 HZ INTERRUPT: This technique Is probably the most versatile and 
practical of all methods available to the ATARI 400/800™ programmer. 

Precisely every 60th of a second, the computer hardware automatically 
generates what Is termed an "interrupt". When this happens, the computer 
temporarily leaves the mainline program, (the program running on the system; 
I.e., BASIC, STAR RAIDERS'"). It then executes an Interrupt service routine, 
a very small routine designed specifically for servicing these Interrupts. 
When the Interrupt service routine finishes, it executes a special machine 
language instruction which restores the computer to the Interrupted program. 
This all occurs In such a way (If done properly) that the program executing 
Is not affected, and In fact has no Idea that It ever stopped! 



The Interrupt service routine currently resident on the ATARI 400/800 w 
simply maintains timers, translates controller Information and miscellaneous 
other chores requiring regular attention. 

But before the Interrupt service routine returns to the mainline 
program, It can be made to execute any user routine; I.e., your sound 
generation routine. This Is Ideal for sound generation since the timing Is 
precisely controlled, and especially since another program can be executing 
without paying heed to the sound generator! 

Even more Impressive Is Its versatility. An Interrupt sound program 
will lend Itself equally well to a mainline program written In any language 
- BASIC, assembler, FORTH, PASCAL. In fact, the sound generator will 
require few If any modifications to work with another program, or even 
another language. 

A table-driven routine offers maximum flexibility and simplicity for 
such a purpose. "Table-driven" refers to a type of program which accesses 
data tables In memory for Its Information. In the case of the sound 
generator, the data tables would contain the frequency values and possibly 
the audio control register values. The routine would simply read the next 
entries In the data table, and put them Into their respective audio 
registers. Using this method, notes could change as often as 60 times per 
second, fast enough for most applications. 

This program must be written In machine language since It Is actually 
becoming a part of the operating system. 

Once such a program has been written and placed In memory (say, at 
location $600), you need to Install It as a part of the 60 hz Interrupt 
service routine. This Is accomplished by a method known as vector stealing, 
and Is described further In appendix I. 

Memory locations $224, $225 contain the address of a small routine 
called XITVBL (eXIT Vertical BLank Interrupt service routine). XITVBL Is 
designed to be executed after all 60 hz Interrupt processing Is complete, 
restoring the computer to the mainline program as previously discussed. 

The procedure to Install your sound routine Is as follows: 



1) place your program In memory 

2) verify that the last Instruction executed Is a JMP $E462. 

($E462 Is XITVBL, so this will make the mainline program continue) 

3) load the x register with the high byte of your routine's address, 
(a 6 in this case) 

4) load the y register with the low byte of your routine's address, 
(a 0 In this case) 

5) load the accumulator with a 7. 

6) do a JSR $E45C (to set locations $224, $225) 
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Steps 3-6 above are all required to change the value of $224, $225 
without error. The routine called Is SETVBV (SET Vertical Blank Vectors), 
which will simply put the address of your routine Into locations $224, $225 
(see appendix I ) . 

Once Installed, the system will work as follows when an Interrupt 
occurs: 

1) the computer's Interrupt routine Is executed 

2) It jumps to the program whose address Is In $224, $225, which Is 
now your routine. 

3) your routine executes. 

4) your routine then Jumps to XITVBL. 

5) XITVBL restores the computer and makes It resume normal operation. 



For comparison, the following shows the Interrupt sequence without your 
routine as a part: 



1) the computer's Interrupt routine executes. 

2) It jumps to the address specified In $224,225, which Is XITVBL. 

3) XITVBL restores the computer to Its pre- Interrupt state, and makes 
the computer resume Its mainline processing. 



If you do not wish to Implement such a program yourself, there Is one 
available. A BASIC editor allows creation and modification of sound data 
while you listen. It Is accompanied by an Interrupt sound generator as 
described above: table driven, compatible with any language. The package Is 
called INSOMNIA (INterrupt SOuNd Initial Izer/Alterer) , and Is offered by the 
Atari Program Exchange. 

MACHINE CODE SOUND GENERATION: Using assembly language opens new 
doors In sound generation. An attempt can now be made to simulate 
particular musical Instruments. The technique Is as follows: write a 
program similar to the 60 hz Interrupt routine In that It Is table-driven. 
The output of that routine will look something like this for 3 music notes: 
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e 

q 



It—note— >| 

figure 10.12 

example of 3 music notes played on a standard music routine 



Since much more processing time Is available, we can go a level deeper, 
minutely changing the frequency during the note f s playing time so that It 
simulates an Instrument. For example, suppose we discovered that whenever a 
piano key Is struck (any key) we can get an Identical sound by very quickly 
playing a table of frequencies. That table may look something like this: 



figure 10.13 

graphed table of frequencies that possibly duplicates a piano key 



Let's call the above table the "envelope table", and Its data a "piano 
envelope". To simulate a piano, the Idea would be to very quickly add the 
piano envelope to the plain vanilla beep. The note is thus slightly modified 
during Its playing time. For example, a piano simulation of the 3 notes In 
figure 10.12 would look like thlss 
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f 



fa 



r 
e 



fa 




|«— note— >| 



figure 10.14 
example of the 3 notes of fig 10.10 
played with a piano envelope 



We have essentially the same sound produced by the standard music 
routine of figure 10.12, only the notes now have a piano flavor, and sound 
much prettier than just the flat "beeps". 

Unfortunately, we had to sacrifice all other processing to get that 
piano flavor. The sound Is no longer updated only once every note, but 
perhaps 100 times within the note's duration. 

Volume only: Earlier we experimented with the AUDC1-4 volume only 
bits, and hinted at a lurking power, but discovered that they seemingly 
weren't of much use. This was due entirely to the fact that BASIC Is too 
slow to effectively use them. Not so with machine language. 

As mentioned earlier, this bit offers a tremendous capacity for 
accurate sound reproduction. True waveform generation (to the time and 
volume resolution limits of the computer) Is now possible. Instead of just 
putting a piano flavor Into the music, you can now make It duplicate a piano 
sound. 

Unfortunately, It can never precisely simulate an Instrument. 4 bits 
(16 values) Is not enough volume resolution, although by no means Is this 
technique rendered fruitless. The following program shows the use of one of 
the volume only bits. If you have an assembler, type It In and try It: 
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0100 
0110 
0120 
0130 
01 4u 
0150 
0160 
0170 
0180 
0190 
0200 
0210 
0220 
0230 
0240 
0250 

0260 
0270 
0280 
0290 
0300 
0310 
0320 
0330 
0340 
0350 
0360 
0370 
0380 
0390 
0400 
0410 
0420 
0430 
0440 
0450 
0460 
0470 
0480 
0490 
0500 
0510 
0520 
0530 
0540 
0550 
0560 
0570 
0580 
0590 
0600 
0610 
0620 
0630 
0640 



VONLY 



Bob Fraser 7-23-81 



volume-only AUDC1-4 bit test routine 



AUDCTL=$D208 
AUDF1=$D200 
AUDC1=$D201 
SKCTL=$D20F 



9 



*=$B0 
TEMPO .BYTE 1 
MSC .BYTE 0 



*=$4000 




LDA #0 




STA AUDCTL 




LDA #3 




STA SKCTL 




LDX #0 




LDA #0 




STA $D40E kill 


vbt 's 


STA $D20E kill 


Irq's 


STA $D400 kill 


dma 



p 

i 



LOO LDA DTAB,X 
STA MSC 

'lda vtab,x 
lo ldy tempo 

STA AUDC1 
L1 DEY 
BNE L1 

; dec most slg ctr 
DEC MSC 
BNE LO 



new note 
I NX 

CPX NC 
BNE LOO 



10-26 



0650 ; wrap note pointer 
0660 LDX #0 
0670 BEQ LOO 
0680 ; 
0690 ; 

0700 NC .BYTE 28 note count 
0710 ; 

0720 : table of volumes to be played In succession 
0730 VTAB 

0740 .BYTE 24,25,26,27,28,29,30,31 
0750 .BYTE 30,29,28,27,26,25,24 
0760 .BYTE 23,22,21,20,19,18,17 
0770 .BYTE 18,19,20,21,22,23 
0780 ; 

0790 ; this table contains the duration of each entry above 
0800 DTAB 

0810 .BYTE 1,1,1,2,2,2,3,6 
0820 .BYTE 3,2,2,2,1,1,1 
0830 .BYTE 1,1,2,2,2,3,6 

0840 .BYTE 3,2,2,2,1,1 y , . 



Suprl singly, speed Is not really problem here. The wave has almost 60 
steps, and the program can still be made to play the wave at a piercing 
level (approx. 10 Khz). 

Remove lines 400-410, and try the program once more. It wll I sound 
quite broken up. The cause Is the 60 hz Interrupt discussed In the previous 
section. You can actually hear the Interrupts taking place since all sound 
stops during that time. 

Line 420 disables screen DMA. This Is why the screen goes to solid 
background color when the program Is executed. It serves two purposes: to 
speed up the processor, and to make the timing consistent, since DMA steals 
cycles at odd Intervals. See Chapter 5 for more on DMA. 

In this particular case, the sound created Is a sine wave. The wave Is 
remarkably pure, and does Indeed sound like a sine wave. If graphed, the 
data looks like this: 
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figure 10.15 

graphed sine wave data for volume only program (above) 



Much can be done with the ATARI 400/800 Wf s sound capabilities. The 
question Is, "Why sound? 11 

Movie makers have long understood the Importance of mood setting 
backgroud music. The recent space adventure movies by George Lucas are 
excellent examples. When the vl I 1 1 an enters the room you know Immediately 
to fear and hate him from the menacing background rhythms accompanying his 
entry. And you gleefully clap your hands when the hero saves the princess 
while gallant music plays excitedly In the background. Horror films can 
frighten you by just playing eerie music, even though the action may be 
completely ordinary. 

SPACE INVADERS'" Issues a personal threat to Its player and victim with 
Its echoing stomp. As the tempo Increases, knuckles whiten and teeth grind. 
When a Zylon from STAR RAIDERS™ fires a photon torpedo you push frantically 
on the control to avoid Impact. As It bores straight for your forehead, 
time slows and you hear It hissing louder and louder as It approaches. Just 
before Impact, you duck and dislodge yourself from your armchair. 

Impressionistic sounds affect our subconclous and our state of mind. 
This Is due possibly to the fact that sounds, If present, are continuously 
entering our mind whether or not we are actively listening. On the other 
hand, If we are distracted from the TV set, we cease to concentrate on the 
picture and the Image leaves our mind. Sound therefore offers the 
programmer a direct path to the user's mind - bypassing his thought 
processes and zeroing In on his emotions. 

Even a very boring game can be made exciting by background mood sounds, 
jubilant success sounds, and chastizing but hopeful failure sounds. These 
can make a game much more popular, although they takes a great deal of 
effort to develop. 
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APPENDIX I 
VERTICAL BLANK INTERRUPTS 



The ATARI 400/800™ provides a number of Interrupts which can be of great 
value. This appendix will cover vertical blank Interrupts. These Interrupts 
are non-maskable Interrupts which occur every 60th of a second during the 
vertical blank time of the television display. They have a wide variety of 
uses. 

At the beginning of vertical blank ANTIC pulls down the NMI line on the 
6502. The 6502 then vectors to an NMI service routine which determines the 
source of the Interrupt. If It Is a vertical blank Interrupt, the 6502 
pushes Its A, X, and Y registers onto the stack and jumps through the 
Immediate vertical blank vector (VVBLKI) located at $0222. This vector 
normally points to the OS vertical blank Interrupt service routine at $E45F. 
This routine terminates by jumping through the deferred vertical blank 
Interrupt vector (VVBLKD) at $0224. Normally this vector points to a simple 
Interrupt termination routine at $E462. Figure 1.1 Illustrates this process. 
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Figure 1.1 

normal vertical blank Interrupt execution 

(and how to steal It) 



These two vectors were put Into RAM to allow the programmer to trap the 
Interrupt service routine and use the 60 Hertz Interrupt for her own 
purposes. The procedure to use them Is rather simple. First decide whether 
the vertical blank Interrupt (VBI) routine Is to be an Immediate VBI or a 
deferred VBI. In many cases It makes little difference which Is chosen. 
There are only a few cases where It matters. The first case arises when your 
VBI routine reads or writes to registers which are shadowed by the OS VBI 
routine For example, It may be necessary to write to the hardware registers 
after the OS VBI routine has written to them so as to have the last word, so 
to speak. 

The second case arises when your VBI routine consumes too much processor 
time. The OS VBI routine may be delayed beyond the end of the vertical blank 
period. This In turn may cause some graphics registers to be changed while 
the beam Is tracing on the screen. The result may be unsightly. If this Is 
the case, your VBI routine should be placed as a deferred VBI routine. Your 
time limit for Immediate VBI routines Is about 3800 machine cycles; for 
deferred VBI routines It Is about 20,000 cycles. However, many of these 
20,000 machine cycles are executed while the electron beam Is being drawn, so 
graphics operations should not be executed In deferred VBI routines. 
Furthermore, display list Interrupt execution time comes out of the time 
available for this processing. Remember also that VBI processing time comes 
out of the mainline execution time. 

The third case arises when your own vertical blank Interrupt must be 
mixed with time-critical 1/0 such as disk or cassette 1/0. The OS vertical 
blank Interrupt routine has two stages, a critical and a non-critical stage. 
During time critical 1/0, the OS VBI routine aborts after stage one 
processing Is complete. If you do not wish your own VBI routine to be 
disabled during time-critical 1/0, you must define It as an Immediate VBI 
routine. The delays you thereby create may Interfere with time-crlttcal 1/0. 
That f s your problem. 

Once you have decided whether your VBI routine should be Immediate or 
deferred, you must place the routine In memory (page six Is an excellent 
place), link Its termination to the regular VBI processing, and modify the 
appropriate OS RAM vector to point to It. Terminate an Immediate VBI routine 
with a JMP to $E45F. Terminate a deferred VBI routine with a JMP to $E462. 
If you desire to bypass the OS VBI routine entirely (and so save some 
processing time), terminate the Immediate VBI routine with a JMP to $E462. 

A common problem with Interrupts on 8-blt micros arises when you try to 
change the vector to the Interrupt. Vectors are two-byte quantities; It 
takes two store Instructions to change them. There Is a small chance that an 
Interrupt will occur after the first byte has been changed but before the 
second byte has been changed. This would crash the system. The solution to 
this problem Is provided by an OS routine called SETVBV at location $E45C. 
Load the 6502 Y-reglster with the low byte of the address, the X-reglster 
with the high byte of the address, and the accumulator with a 6 for Immediate 
VBI or a 7 for deferred VBI. Then JSR SETVBV and the Interrupt will be 
safely enabled. It will begin executing within one 60th of a second. 
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A wide variety of operations can be performed with 60 Hertz Interrupts. 
First, screen manipulations can be done during the vertical blank to Insure 
that transitions do not occur on scre cr Second, high speed regular screen 
manipulations can be performed. This Is Important In showing many types of 
animation. For example, the bubbles In the nuclear reactor program SCRAM™ 
must move at a regular pace. They must not speed up or slow down as other 
computational activities burden the 6502. The only way to assure the 
regularity of their motion Is to perform the animation during a vertical 
blank Interrupt. 

Another function of vertical blank interrupts Is for sound envelope 
generation. The sound registers In the ATARI 400/800™ allow control of 
frequency, volume, and distortion, but not duration. Duration can be 
controlled with a vertical blank Interrupt by having the calling routine set 
a duration parameter Then the vertical blank Interrupt routine decrements any 
nonzero duration parameter and turns off the sound when the duration 
parameter reaches zero. This technique can be used to control the volume of 
the sound and so give attack and decay envelopes to sounds. Control of 
frequency and distortion Is possible with extended versions of this 
technique. These techniques can produce very Intricate sound effects. 
Because the time resolution Is only 1/60th of a second, VBI f s are not useful 
for direct control of speaker amplitude. 

Vertical blank Interrupts are also useful for handling user Inputs. 
These Inputs require little computation but constant attention. A vertical 
blank Interrupt allows the program to check for user Input every 60th of a 
second without otherwise burdening the program. It Is an Ideal solution to 
the problem of maintaining computational continuity without Ignoring the 
user. 

Finally, vertical blank Interrupts allow a crude form of multitasking to 
take place. A foreground program can run under the vertical blank Interrupt 
while a background program runs in the mainline. As with any Interrupt, 
careful separation of the databases for the two programs must be maintained. 
However, the power obtained may well be worth the effort. 



APPEND I X I I 
HUMAN ENGINEERING 

The ATARI Personal Computer System Is first and foremost a consumer 
computer. The hardware was designed to make this computer easy for consumers 
to use. There are many hardware features which protect the consumer from 
Inadvertent errors. Software written for this computer should reflect an 
equal concern for the frailties of the consumer. The average consumer Is not 
stupid; he Is unfamiliar with the conventions and traditions of the computer 
world. Once he understands a program he will use It well most of the time. 
Occasionally he will be careless and make mistakes. It Is the programmer's 
responsibility to protect the consumer from his own mistakes. 

The current state of software human engineering In the personal computer 
Industry Is dismal. A great many programs are being sold which contain very 
poor human engineering. The worst offenders are written by amateur 
programmers, but even software written at some of the largest firms shows 
occasional lapses In human engineering. 

Human engineering Is an art, not a science. It demands great technical 
skill but It also requires Insight and feel. As such It Is a highly 
subjective field devoid of absolutes. This appendix Is the work of one hand, 
and so betrays the subjectivities of Its author. A proper regard for the 
wide variety of opinions on the subject would have Inflated this appendix 
beyond all reasonable limits of length. Furhermore, a complete presentation 
of all points of view would only confuse the reader with Its many assertions, 
qualifications, counterpoints, and contradictions. I therefore chose the 
simpler task of presenting only my own point of view, giving weak lip service 
to the most serious objections. The result Is contradictory enough to 
satisfy even the most academic of readers. 

THE COMPUTER AS SENTIENT BEING 

An Instructive way of viewing the problem of human engineering Is to 
cast the programmer as sorcerer, conjuring up an Intelligent being, a 
homunculus, within the Innards of the computer. This creature lacks physical 
embodiment, but possesses Intellectual traits, specifically, the ability to 
process and organize Information. The user of the program enters Into a 
relationship with this homunculus. The two sentient beings think 
differently; the human's thought patterns are associative, Integrated, and 
diffuse, while the program's thought processes are direct, analytical, and 
specific. These differences are complementary and productive because the 
homunculus can do well what the human cannot. Unfortunately, these 
differences also create a communications barrier between the human and the 
homunculus. They have so much to say to each other because they are so 
different, but because they are different they cannot communicate well. The 
central problem In good programming must therefore be to provide for better 
communications between the user and the homunculus. Sad to say, many 
programmers expend the greater part of their efforts on expanding and 
Improving the processing power of their programs. This only produces a more 
Intelligent being with no eyes to see and no mouth to speak. 

The current crop of personal computers have attained throughputs which 
make them capable of sustaining programs Intel I Igent enough to meet many of 
the average consumer's needs. The primary limiting factor Is no longer clock 
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speed or resident memory; the primary limiting factor Is the thin pipeline 
connecting our now-t ntel I Igent homunculus with his human user. Each can 
process Information rapidly and efficiently; only the narrow pipeline between 
them slows down the Interaction. 



COMMUNICATION BETWEEN HUMAN AND MACHINE 

How can we widen the pipeline between the two thinkers? We must focus 
on the language with which they communicate. Like any language, a 
man-machine language Is restricted by the physical means of expression 
available to the speakers. Because the computer and the human are physically 
different, their modes of expression are physically different. This forces 
us to create a language which Is not bidirectional (as human languages are). 
Instead, a man-machine language will have two channels, an Input channel and 
an output channel. Just as we study human language by first studying the 
sounds that the human vocal tract can generate, we begin by examining the 
physical components of the man-machine Interface. 



OUTPUT (FROM COMPUTER TO HUMAN) 

There are two primary ouput channels from the computer to the user. The 
first Is the television screen; the second Is the television speaker. 
Fortunately, these are flexible devices which permit a broad range of 
expression. The main body of this book describes the features available from 
the computer's point of view. For the purposes of this appendix, It Is more 
useful to discuss these devices In terms of the human point of view. Of the 
two devices (screen and speaker) the display screen Is easily the more 
expressive and powerful device. The human eye Is a more finely developed 
Information gathering device than the human ear. In electrical engineering 
terms, It has more bandwidth than the ear. The eye can process three major 
forms of visual Information: shapes, color, and animation. 

Shapes 

Shapes are an Ideal means for presenting Information to the human. The 
human retina Is especially adept at recognizing shapes. The most direct use 
of shapes Is for direct depiction of objects. If you want the program to 
tell the user about something, draw a picture of It. A picture Is direct, 
obvious, and Immediate. 

The second use of shapes Is for symbols. Some concepts In the human 
lexicon defy direct depiction. Concepts like love, Infinity, and direction 
cannot be shown with pictures. They must Instead be conveyed with symbols, 
such as a heart, a horizontal figure 8, or an arrow. These are a few of the 
many symbols that we all recognize and use. Sometimes you can create an ad 
hoc symbol for limited use In your program. Most people can pick up such an 
ad hoc symbol quite readily. Symbols are a compact way to express an Idea 
but they should not be used In place of pictures unless compactness Is 
essential. A symbol Is an Indirect expression; a picture Is a direct 
expression. The picture conveys the Idea more forcefully. 
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The third and most common use of shapes Is for text. A letter Is a 
symbol; we put letters together to form words. The language we thereby 
produce Is extremely rich In Its expressive power. Truly Is It said, "If you 
can f t say It, you don't know It." This expressive power Is gained at a 
price: extreme Indirection. The word that expresses an Idea has no sensory 
or emotional connection with the Idea. The human Is forced to carry out 
extensive mental gymnastics to decipher the word. Of course, we do It so 
often that we have become quite fluent at translating strings of letters Into 
Ideas. We do not notice the effort. The Important point Is that the 
Indirection detracts from the Immediacy and forceful ness of the 
communication. 

There Is a school of thought that maintains that text Is superior to 
graphics for communications purposes. The gist of the arguement Is that text 
encourages freer use of the reader's rich Imagination. The arguement does 
not satisfy me, for If the reader must use his Imagination, he Is supplying 
Information that Is not inherent in the communication Itself. An equal 
exercise of Imagination with graphics would provide even greater results. A 
more compelling arguement for text Is that Its Indirection allows It to pack 
a considerable amount of Information Into a small space. The space 
constraints on any real communication make text's greater compactness 
valuable. Nevertheless, this does not make text superior to graphics; It 
makes text more economical. Graphics requires more space, time, memory, or 
money, but It also communicates better than text. To some extent, the choice 
between graphics and text Is a matter of taste, and the taste of the buying 
public Is beyond question. Compare the popularity of television with that of 
radio, or movies with books. Graphics beats text easily. 

Color 

Color Is another vehicle for conveying Information. It Is less powerful 
than shape, and so normally plays a secondary role to shape In visual 
presentations. Its most frequent use Is to differentiate between otherwise 
Indistinguishable shapes. It also plays an Important role In providing cues 
to the user. Good color can salvage an otherwise ambiguous shape. For 
example, a tree represented as a character must fit Inside an 8x8 pixel grid.* 
The grid Is too small to draw a recognizable tree; however, by coloring the 
tree green, the Image becomes much easier to recognize. Color Is also useful 
for attracting attention or signalling Important material. Hot colors 
attract attention. Color also provides aesthetic enhancement. Colored 
Images are more pleasing to look at than black and white Images. 

Animation 

I use the term "animation" here to designate any visual change. 
Animation Includes changing colors, changing shapes, moving foreground 
objects, or moving the background. Animation's primary value Is for showing 
dynamic processes. Indeed, graphic animation Is the only way to successfully 
present highly active events. The value of animation Is most forcefully 
demonstrated by a game like STAR RAIDERS". Can you imagine what the game 
would be like without animation? For that matter, can you imagine what it 
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would be like In pure text? The value of animation extends far beyond games. 
Animation allows the designer to clearly show dynamic, changing events. 
Animation Is one of the major advantages that computers have over paper as an 
Information technology. Finally, animation Is very powerful In sensory 
terms. The human eye Is organized to respond strongly to changes In the 
visual field. Animation can attract the eye's attention and Increase the 
user's Involvement In the program. 

Sound 

Graphics images must be looked at to have effect. Sound can reach the 
user even when the user Is not paying direct attention to the sound. Sound 
therefore has great value as an annunciator or warning cue. A wide variety 
of beeps, tone, and grunts can be used to signal feedback to the user. 
Correct actions can be answered with a pleasant bell tone. Incorrect actions 
can be answered with a raspberry. Warning conditions can be noted with a 
honk. 

Sound has a second use: providing realistic sound effects. Quality 
sound effects can greatly add to the Impact of a program because the sound 
provides a second channel of Information flow that Is effective even when the 
user Is visually occupied. 

Sound Is ill-suited for conveying straight factual Information; most 
people do not have the aural acuity to distinguish fine tone differences. 
Sound Is much more effective for conveying emotional states or responses. 
Most people have a large array of associations of sounds with emotional 
states. A descending sequence of notes Implies deteriorating circumstances. 
An explosion sound denotes destruction. A fanfare announces an Important 
arrival. Certain note sequences from widely recognized popular songs are 
Immediately associated with particular feelings. For example, In ENERGY 
CZAR 1 ", I used a funeral dirge to tell the user that his energy mismanagement 
had ruined America's energy situation, and a fragment of "Happy Days Are Here 
Again 11 to indicate success. 



INPUT DEVICES (FROM HUMAN TO COMPUTER) 

There are three input devices most commonly used with the Atari Personal 
Computer Sytem. These are the keyboard, joystick, and paddles. 

Keyboard 

The keyboard Is easily the most powerful Input device available to the 
designer. It has over fifty direct keystrokes Immediately available. Use of 
the CONTROL and SHIFT keys more than doubles the number of distinguishable 
entries the user can make. The CAPS/LOWR and ATARI keys extend the 
expressive range of the keyboard even further. Thus, with a single keystroke 
the user can designate one of 125 commands. A pair of keystrokes can address 
more than 15,000 selections. Obviously, this device Is very expressive; It 
can easily handle the communications needs of any program. For this reason 
the keyboard Is the input device of choice among programmers. 
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While the strengths of the keyboard are undeniable, Its weaknesses are 
seldom recognized. Its first weakness Is that not many people know how to 
use It well. Programmers use keyboards heavily In their dally work and 
consequently they are fast typists. The average consumer Is not so 
comfortable with a keyboard. He can easily hit the wrong key. The very 
existence of all those keys and the knowledge that one must strike the 
correct key Is Itself Intimidating to most people. 

A second weakness of the keyboard Is Its Indirection. It Is very hard 
to attach direct meaning to a keyboard. A keyboard has no obvious emotional 
or sensory significance. The new user has great difficulty linking to It. 
All work with the keyboard Is symbolic, using buttons which are marked with 
symbols which are assigned meaning by the circumstances. The Indirection of 
It all can be most confusing to the beginner. Keyboards also suffer from 
their natural association with text displays; I have already discussed the 
weaknesses of text as a medium for Information transfer. 

Another property of the keyboard that the designer must keep In mind Is 
Its digital nature. The keyboard Is digital both In selection and In time. 
This of course provides some protection against errors. Because keystroke 
reading over time Is not contlnous but digital, the keyboard Is not 
well-suited to real-time applications. Since humans are real-time creatures, 
this Is a weakness. The designer must realize that use of the keyboard will 
nudge him away from real-time Interaction with his target user. 

Padd I es 

Paddles are the only truly analog Input devices readily available for 
the system. As such they suffer from the standard problem all analog Input 
devices share: the requirement that the user make precise settings to get a 
result. Their angular resolution Is poor, and thermal effects produce some 
jitter In even an untouched paddle's output. 

Their primary value Is two-fold. First, they are well-suited for 
choosing values of a one-d I mens tonal variable. People can Immediately pick 
up the Idea that the paddle sweeps through all values, and pressing the 
trigger makes the selection known. Second, the user can sweep from one end 
of the spectrum to the other with a twist of the dial. This makes the entire 
spectrum of values Immediately accessible to the user. 

An Important factor In the use of paddles Is the creation of a closed 
Input/output loop. In most Input processes, It Is desirable to echo Inputs 
to the screen so that the user can verify the Input he has entered. This 
echoing process creates a closed Input/output loop. Information travels from 
the user to the Input device to the computer to the screen to the user. 
Because the paddle has no absolute positions, echoing Is essential. 

Any set of Inputs that can be meaningfully placed along a linear 
sequence can be addressed with a paddle. For example, menus can be addressed 
with a paddle. The sequence Is from the top of the menu to the bottom. It 
Is quite possible (but entirely unreasonable) to substitute a paddle for a 
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keyboard. The paddle sweeps through the letters of the alphabet, with the 
current letter being addressed shown on the screen. Pressing the paddle 
trigger selects the letter. While the scheme would not produce any typing 
speed records, It Is useful for children and the Idea could be applied to 
other problems. 

Joysticks 

Joysticks are the simplest Input devices available for the computer. 
They are very sturdy and so can be used In harsh environments. They contain 
only five switches. For this reason their expressive power Is frequently 
underestimated. However, joysticks are surprisingly useful Input devices. 
When used with a cursor, a joystick can address any point on the screen, 
making a selection with the red button. With proper screen layout, the 
Joystick can thus provide a wide variety of control functions. I have used a 
joystick to control a nuclear reactor (SCRAM 1 ") and run a wargame (EASTERN 
FRONT 1941). 

The key to the proper use of the joystick Is the realization that the 
critical variable Is not the selection of a switch, but the duration of time 
for which the switch Is pressed. By controlling how long the switch Is 
pressed, the user determines how far the cursor moves. This normally 
requires a constant velocity cursor. A constant velocity cursor Introduces a 
difficult trade-off. If the cursor moves too fast, the user will have 
difficulty positioning It on the Item of choice. If the cursor moves too 
slowly, the user will become Impatient waiting for It to traverse long screen 
distances. One solution to this problem Is the accelerating cursor. If the 
cursor starts moving slowly and accelerates, the user can have both fine 
positioning and high speed. 

The real value of the joystick Is Its high tactlllty. The joystick 
Involves the user In his Inputs In a direct and sensory way. The tactlllty 
of the keyboard Is not emotionally significant. A joystick makes 

sense push up to go up, down to go down. If the cursor reflects this on 

the screen, the entire Input process makes much more sense to the user. 

Joysticks have their limitations. Although It Is possible to press the 
Joystick In a diagonal direction and get a correct reading of the direction, 
the directions are not distinct enough to allow diagonal entries as separate 
commands. Just as some words (e.g. "library", "February") are hard to 
enunciate clearly, so too are diagonal orders hard to enter distinctly. 
Thus, diagonal values should be avoided unless they are used In the pure 
geometrical sense: up on the joystick means up, right means right, and 
diagonally means diagonally. 



SUMMARY OF COMMUNICATIONS ELEMENTS 

I have discussed a number of features and devices which taken together 
constitute the elements of a language for Interaction between the computer 
and the user. They are: 
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CONSTRUCTING A LANGUAGE 

How do we assemble all of these elements Into an effective language? To 
do so, we must first determine the major traits we expect of a good language. 
These are: 

Comp I eteness 

The language must completely express all of the Ideas that need to be 
communicated between the computer and the user. It need not express Ideas 
Internal to either thlnker f s thought processes. For example, the language 
used In STAR RAIDERS™ must express all concepts related to the control of the 
vessel and the combat situation. It need not express the player's anxiety or 
the flight path Intentions of the Zylons. These concepts, while very germane 
to the entire game function, need not be communicated between user and 
computer. 



Completeness Is an obvious function of any language, one that all 
programmers recognize Intuitively. Problems with completeness most often 
arise when the programmer must add functions to the program, functions which 
cannot be supported by the language she has created. This can be quite 
exasperating, for In many cases the additional functions are easily 
Implemented In the program Itself. The limiting factor Is always the 
difficulty of adding new expressions to the I/O language. 

Directness 

Any new language Is hard to learn. No user has time to waste In 
learning an unnecessarily florid language. The language a programmer creates 
for a program must be direct and to the point. It must rely as much as 
possible on communications conventions that the user already knows. It must 
be emotionally direct and obvious. For example, a CONTROL X keystroke Is 
obscure. What does It mean? Perhaps It means that something should be 
destroyed; X Implies elimination or negation. Perhaps It Implies that 
something should be examined, expunged, exhumed, or something similar. If 
none of these possibilities are Indeed the case, then the command Is 
unacceptably Indirect. Keyboards are notorious for creating this kind of 
problem. 

Closure 



Closure Is the aspect of communications design that causes the greatest 
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problems. The concept Is best explained with an analogy. The user is at 
point A and wishes to use the program to get to point B. A poorly 
human-engineered program Is like a tightrope stretched between points A and 
B. If the user knows exactly what to do and performs perfectly, she will 
succeed. More likely, she will slip and fall. Some programs try to help by 
providing a manual or Internal warnings that tell the user what to do and 
what not to do. These are analogous to signs along the tightrope advising 
"BE CAREFUL" and "DON'T FALL". I have seen several programs that place signs 
underneath the tightrope, so that the user can at least see why she failed as 
she plummets. A somewhat better class of programs provide masks against 
Illegal entries. These are equivalent to guardrails alongside the tightrope. 
These are much nicer, but they must be very well constructed to Insure that 
the user does not thwart them. Some programs have nasty messages that bark 
at the errant user, warning her not to make certain entries. These are 
analogous to scowling monitors In the school halls, and are useful only for 
making an adult feel like a child. The Ideal program Is like a tunnel bored 
through solid rock. There Is but one path, the path leading to success. The 
user has no options but to succeed. 

The essence of closure Is the narrowing of options, the elimination of 
possibilities, the placement of rock solid walls around the user. Good 
design Is not an accumulative process of piling lots of features onto a basic 
architecture; good design requires the programmer to strip away minor 
features, petty options, and general trivia. 

This thesis clashes with the values of many programmers. Programmers 
crave complete freedom to exercise power over the computer. Their most 
common complaint against a program Is that It somehow restricts their 
options. Thus, deliberate advocacy of closure Is met with shocked 
Incredulity. Why would anyone be so foolish as to restrict the power of this 
wonderful tool? 

The answer lies In the difference between the consumer and the 
programmer. The programmer devotes his life to the computer; the consumer Is 
a casual aqualntance at best. The programmer uses the computer so heavily 
that It Is cost-effective to take the time to learn to use a more powerful 
tool. The consumer does not have the time to lavish on the machine. He 
wants to get to point B as quickly as possible. He does not care for the 
fine points that occupy a programmer's life. Bells and whistles cherished by 
programmers are only obfuscatory trivia to him. You as a programmer may not 
share the consumer's values, but If you want to maintain your livelihood you 
damn well better cater to them. 

Closure Is obtained by creating Inputs and outputs that do not admit 
Illegal values. This Is extremely difficult to do with a keyboard, for a 
keyboard always allows more entries than any real program would need. This 
Is an excellent arguement against the use of the keyboard. A joystick Is 
much better, because you can do so little with It. Because It can do so 
little, It Is easier to conceptually exclude bad Inputs. The Ideal Is 
achieved when ail necessary options are expressible with the joystick, and no 
further options will fit. In this case the user cannot make a bad entry 
because It doesn't exist. More Important, like Newspeak in Orwell's 1984, 
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the user cannot even conceive bad thoughts because no words (Inputs) for them 
even exist. 

Closure Is much more than masking out bad Inputs. Masking makes bad 
Inputs conceivable and expressible, but not functional. For examle, a 
keyboard might be used with the ff M ,f key disabled because It Is meaningless. 
The user can still see the key, he can Imagine pressing It, and he can wonder 

what would happen If he did press It all wasted effort. The user can waste 

even more time by pressing It and wondering why nothing happened. The waste 
Is compounded by the programmer Imagining the user doing all these wasteful 
things and putting In code to stop the symptoms without eliminating the 
disease. By contrast, a properly closed Input structure uses an Input device 
which can express only the entries necessary to running the program, and 
nothing more. The user can f t waste time messing with something that Isn f t 
there. 

The advantages that accrue when closure Is properly applied are 
manifold. Code Is tighter and runs faster because there need be no Input 
error checking; such errors are obsolete In the new society, er, program. 
The user requires less time to learn the program and has fewer problems with 
It. 

The primary problem with closure Is the design effort that must be 
expended to achieve good closure. The entire relationship between the user 
and the program must be carefully analyzed to determine the minimum 
vocabulary necessary for the two to communicate. Numerous schemes of 
communication must be examined and discarded before the true minimum scheme 
Is found. In the process, many bells and whistles that the programmer wanted 
to add will have to be eliminated. If the programmer objectively looks 
beyond her own values, she will often conclude that the bells and whistles 
are more clutter than chrome. 



CONCLUSIONS 

The design of the language of communication between the user and the 
program will be the most difficult part of the design process In consumer 
software. The designer must carefully weigh the capabilities of the machine 
and the needs of the user. He must precisely define the Information that 
must flow between the two sentient beings. He must then design his language 
to maximize the clarity (not the quantity) of Information flowing to the user 
while minimizing the effort the user must expend to communicate with the 
computer. His language must utilize the machlne f s features and devices 
effectively while maintaining Its own completeness, directness, and closure. 



SOME COMMON PROBLEMS IN HUMAN ENGINEERING 

Having discussed the problems of human engineering In theoretical terms, 
I now turn to discuss specific application problems In human engineering. 
The list of problems Is not exhaustive; It merely covers some of the problems 
common to almost all programs. 
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DELAY TIMES 

Many programs require extensive computations. Indeed, almost all 
programs execute at some time computations that take more than a few seconds 
to perform. What does the user experience while these computations are 
executed? Too many programs simply stop the dialogue with the user for the 
duration of the computation. The user Is left with an Inactive screen and no 
sign of life from the computer. The computer does not respond to the user's 
Inputs. If human engineering Is created by the language of communication 
between the computer and the user, then this complete absence of 
communication can only be regarded as a total lack of human engineering. 
Leaving the user In the lurch like this Is absolutely unf org Iveab le. 

Separate processes 

The best way to deal with the problem of reconciling computations with 
attentlveness Is to separate the Input process from the computational 
process. The user should be able to make inputs while the computations are 
proceeding. This Is technically achievable; by using vertical blank 
Interrupts (see Appendix I) the programmer can multitask input processing 
with mainline processing. The technique Is used In EASTERN FRONT 1941. The 
real problem with the technique Is that many problems are Intrinsically 
sequential In nature. It Is essential for the user to Input a value or 
choice before the computation can proceed to the next step. This makes It 
difficult to separate Input processing from the mainline processing. 
However, It Is possible with clever design to perform anticipatory 
calculations that will determine Intermediate values so that as soon as the 
critical data Is entered, the result might be more quickly obtained. 
Application of such techniques can surely reduce the delay times that the 
user experiences. 

Speed up the program 

Another means of dealing with this problem Is to speed up the program 
Itself. Critical code can often be rewritten to decrease execution time. 
Proper nesting of loops (the loop with more Iterations should be Inside the 
loop with fewer Iterations) can reduce execution time. Careful attention to 
the details of execution can yield further time reductions. Major gains can 
be made by converting BASIC to assembly language. Assembly Is from 10 to 
1000 times faster than BASIC. Assembly's advantage Is greatest for memory 
move routines and graphics and least for floating point calculations. By 
masking out vertical blank Interrupts, more 6502 execution time can be freed 
up for mainline processing. Other gains can be accomplished by reducing the 
DMA overhead ANTIC Imposes. This can be done by going to a simple graphics 
mode (BASIC mode 3 Is best). Shortening the display list Is another way to 
reduce DMA costs. Turning off ANTIC altogether is a drastic route which only 
creates the additional problem of presenting the user with a blank screen. 

Entertain the user 
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The third way to deal with delay times Is to occupy the user during the 
computation. A countdown Is one such method. The user seesD&ntdown on 
the screen. When the countdown reaches zero, the program Is back In 
business. Another way Is to draw random graphics on the screen. The delay 
period should always start with a courteous message advising the user of the 
delay. It should also be terminated with a bell or other annunciator. You 
should not expect the user to keep his eyes on the screen for an arbttrary 
period of time. Entertaining the user during delays Is a poor way to deal 
with delays that shouldn't have been there In the first place, but It's 
better than abandoning the user. 



DEALING WITH BAD USER INPUTS 

The most serious problem with present consumer software Is the sloppy 
way that bad user Inputs are handled. Good designs preclude this problem by 
providing Input languages which do not make any bad entries available. As I 
pointed out earlier, this Is most easily accomplished with a Joystick. 
However, there are applications (primarily text- 1 n tens I ve ones) which require 
a keyboard. Furthermore, even Joysticks occasionally Introduce problems with 
user Input. How are such bad Inputs to be dealt with when they cannot be 
expunged? Several suggestions follow. It Is Imperative that any protection 
system be applied uniformly throughout the entire program. Once the user 
encounters protection, she will expect It In all cases. The lack of such 
protection creates a gap through which the user, thinking herself secure, 
wl 1 1 surely plunge. 

Flag the error and suggest solution 

The most desirable approach In this unpleasant situation Is to flag the 
user's error on the screen In plain language and suggest a correct entry. 
Three things must be Included the computer's response. First, the user's 
entry must be echoed back so he knows what he did that caused the problem. 
Second, the offending component of the entry must be clearly marked and 
explained so that the user knows why It Is wrong. Third, an alternate legal 
entry must be suggested so that the user does not become frustrated by the 
feeling that he has encountered a brick wall. For example, an appropriate 
response to a bad keystroke entry might read thusly: "You pressed CONTROL-A, 
which Is an autopsy request. I cannot peform autopsies on living people. I 
suggest you kill the subject first." 

This method Is obviously very expensive In terms of program size and 
programming time. That Is the price one pays for bad design. There are less 
expensive and less effective methods. 

Masking out bad keys 

One common solution to keyboard Input problems Is to mask out all bad 
entries. If the user presses a bad key, nothing happens. No keyboard click 
Is generated and no character appears on the screen. The program only hears 
what It wants to hear. This solution Is secure In that It prevents program 
crashes, but It does not protect the user from confusion. The user would 
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only press a button If he felt that It would do something for htm. Masking 
out the button cannot correct the user's mistaken Impression. It can only 
lead him to the conclusion that something Is seriously wrong with his 
computer. We don't want to do this to our users. 

A variant on this scheme Is to add a nasty buzzer or raspberry to 
chastise the user for his foolishness. Indeed, some amateurish programs go 
so far as to heap textual abuse on the user. Such techniques are highly 
questionable. There may Indeed be cases requiring dangerous keystroke 
entries which are guarded by fierce and nasty messages; such cases are quite 
rare. Corrective messages should always conform to high standards of 
civil Ity. 

Error messages 

An even cheaper solution Is to simply post an error message on the 
screen. The user Is told only that he did something wrong. In many cases, 
the error message Is cryptic and does not help the user In the least. ATARI 
BASIC Is an extreme example of this. Error messages are provided by number 
only. This can be justified only when the program must operate under very 
tight memory constraints. 

In most cases, the designer chooses to sacrifice human engineering 
features such as meaningful error messages for some additional technical 
power. As pointed out In the beginning of this appendix, we are reaching the 
stage In which additional technical power Is no longer a limiting factor to 
consumers, but human engineering Is a limiting factor. Thus, the trade-off 
Is less Justifiable. 

Protect I on/ power trade-offs 

One objection to many human engineering features Is that they slow down 
the user's Ineractlon with the computer. Programmers tire of Incessant "ARE 
YOU SURE?" requests and similar restrictions. One solution to this problem 
Is to provide variable protect I on/ power ratios. For example, a program can 
default to a highly protected state on Initialization. All entries are 
carefully checked and echoed to the user for confirmation. The user has an 
option to shed protection and work In high-speed mode. This option Is not 

obvious from the screen It Is only described In the documentation. Thus, 

the Intensive user can work at her pace and the casual user can have adequate 
protection. 



MENUS AND SELECTION TECHNIQUES 

Menus are standard devices for making the user aware of the options 
available. They are especially useful for beginning users. Command-oriented 
schemes preferred by programmers confuse beginners who cannot afford the time 
Investment to learn the lexicon of commands used by a command-oriented 
program. There are several common problems associated with the use of menus. 
I shall discuss some of these. 
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Menu size 

How many entries should be on a menu? The obvious upper limit Is 
dictated by the size of the screen, but this limit Is too large, for a BASIC 
mode 0 screen could hold up to 48 entries (24 lines with two choices per 
line). My guess Is that 7 entries Is the desired upper limit on menu size. 
This allows plenty of screen space to separate the entries, provide a menu 
title, and some sort of prompt. 

Multiple menus 

Frequently a program will require several menus to fully cover all of 
the options It offers. It Is very Important that multiple menus be organized 
In a clear manner. The user can easily get lost wandering around through 
such menu mazes. One way Is to have a main menu that Is prominently marked 
as such, and provide each secondary menu with an option to return to the main 
menu. Another way Is to nest menus In a hierarchical structure. When using 
such methods, the programmer must provide color and sound cues to help the 
user ascertain his position In the menu structure. Each menu or menu level 
should have a distinctive note or color assigned to It. The note frequency 
should be associated with the position In the hierarchy. 

Selection methods 

Once the user has seen his options, how does he make his choice known to 
the computer? The most common way Is to label each entry on the menu with a 
letter or number; the user makes his selection by pressing the corresponding 
key on the keyboard. This Is a clumsy solution Involving unnecessary 
Indirection. There are a number of better methods. Most of them use the 
same basic scheme: a movable pointer addresses an option, and a trigger 
selects It. One scheme I have seen highlights the option being addressed In 
Inverse video. The SELECT button changes the pointer to address the next 
menu selection, with full wraparound from the end of the menu to the 
beginning. The START button engages a menu option. Another program I have 
seen automatically rotated the pointer through the menu options; the user 
need only push a button at the correct moment when his desired option was 
being addressed. (I wasn't overly Impressed by that method.) Paddles and 
Joysticks are very well suited for menu selection. Either one can be used to 
sweep the pointer through the menu selections, with the red trigger button 
making the selection. My pet scheme for menu selection uses a cursor on a 
large scrolling menu. The user moves the cursor with a joystick. Signposts 
can direct her to different regions of the menu. She makes her selection by 
placing the cursor directly on top of an option and pressing the trigger 
button. 



MANUALS VERSUS ON-BOARD TEXT 

A common problem with menus, error messages, prompts, and other messages 
Is that such material can easily consume a large amount of memory, memory 
that could well be used for other features. Such material could be placed In 
a reference document, but doing so would detract from the quality of the 
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program's human engineering. The designer must decide how much material 
should go Into the program and how much should be relegated to the manual. 
With disk-based programs It Is possible to store some of the material on the 
diskette; this lessens the harshness of the trade-off. When the problem Is 
approached only from the human engineering point of view, It Is easily 
answered: all material should be Included In the program, or at least on a 
diskette. Economic and technical considerations argue against this. It Is 
my personal view that each technology should be used for the things It does 
best. While the computer can handle static text, Its forte Is dynamic 
Information processing. Paper and Ink handle static Information more cheaply 
and often more clearly than a computer. I therefore prefer to put static 
Information Into a manual and let the program refer the user to the manual. 
I still Include critical Information within the program; my dividing line 
bends with local needs. 



MEASURES OF SUCCESS 

How can a designer determine the success of his human engineering? 
There are several Indicators that provide valuable feedback. The first Is 
the minimum length length of the manual. If you exclude background material 
and Isolate only the material In the manual that Is absolutely necessary to 
describe how to use the program, then the length of this material Is a good 
measure of your human engineering. The more material, the worse you've done. 
A well-designed program should require very little explanation. This should 
not be construed as an arguement against proper documentation. Documentation 
should always describe the program In more detail than Is absolutely 
necessary. A long, lavish manual Is good; a program that demands such a 
manual Is not. 

Another measure Is the amount of time that a first-time user expends to 
learn to use the program satisfactorily. Good programs can be used In a 
matter of minutes. 

A third measure Is the amount of thinking a user must do to use the 
program. A well-designed program should require no cognitive effort to use. 
This does not mean that the user does not think at all while using such a 
program. Rather, he thinks about the content 6f the program rather than the 
mechanics of the program. He should concentrate on what he Is doing, not how 
he does It. 

The we I I -engineered program eliminates mental distance between the user 
and the computer. The two thinking beings achieve a mental syntony, an 
Intellectual communion. 
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ATARI CASSETTE OVERVIEW 



This is a discussion of the ATARI 410 1 " Program Recorder. The following 
topics will be included: 

1. How the cassette works - information on the hardware and software 
used to operate the cassette. 

2. Cassette applications - how to mix audio and digital information 
to produce a very user oriented program. 
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HOW THE CASSETTE WORKS 



1.1 RECORD STRUCTURE 
Byte Definition : 

The OS writes files in fixed-length blocks at 600 baud (physical 
bits/second). Asynchronous serial transmission is used to read and write 
data between the ATARI PCS and the ATARI 410. POKEY recognizes each data 
byte in this order: 1 start bit (space), eight data bits (0=space, 1=mark), 
then one stop. bit (mark). A byte is sent/received least significant bit 
first. 

The frequency used to represent a mark is 5327 Hz. For a space the 
frequency is 3995 Hz. The data byte format is as follows: 

0 2 4 6 B MARK 

I I I I I I I I 1 I ~ 

I A I I 1 | I 3 I I 5 I I 7 I SPACE 



A = Start Bit (Space) 

0-7 = Data Bits 

B = Stop Bit (Mark) 



Record Definition : 

Records are 132 bytes long. A record is broken down in the following 
way: 2 marker characters for speed measurement, a control byte, 128 data 
bytes, and the checksum byte. The record format is shown below: 



0 10 10 10 1 



0 10 10 10 1 



1st MARKER 



2nd MARKER 



(For Speed 
Measurement) 



CONTROL BYTE 



128 
DATA 
BYTES 



CHECKSUM 



1st and 2nd MARKER: 



Each marker character is a 55 (HEX). Including start and stop bits, 
each marker is 10 bits long. Ideally, there should be no blank tape 
between the markers and the subsequent data. 



III-2 



ATARI CASSETTE 



Speed Measurement : 

The purpose of the marker characters is to adjust the baud rate. 

The input baud rate is assumed to be a nominal 600 baud. This is 
adjusted, however, by the SIO routine to account for drive motor variations, 
stretched tape, etc. Once the true receive baud rate is calculated, the 
hardware is adjusted accordingly. Input baud rates ranging from 318 to 
1407 baud can theoretically be handled using this technique. 

The OS checks the tape speed in the following manner: The software 
looks at the POKEY Serial-In bit continuously. Looking for a start (0 
bit) which signifies the beginning of a record. When it finds one, the 
OS stores the current frame counter by saving the ANTIC VCOUNT (vertical 
screen counter). Continuing to look directly at the Serial-In bit, the 
OS counts the twenty bits (end of the 2 markers), then uses VCOUNT and the 
frame counter to determine the elapsed time. The baud rate to use is 
derived from the result. This is done for each record. 



Control Byte : 

The control byte contains one of three values: 

$FC indicates the record is a full data record (128 bytes). 

$FA indicates the record is a partially full data record; fewer 
than 128 bytes were supplied by the user. This case may occur only 
in the record prior to the end-of-file. The actual number of data 
bytes, 1 to 127, is stored in the last data byte prior to the 
checksum; i.e. the 128th data byte. 

$FE indicates the record is an end-of-file record and is followed by 
128 zero bytes. 



Checksum : 

The checksum is generated and checked by the SIO routine, but is not 
contained in the cassette handler's I/O buffer CASBUF [03FD]. 

The checksum is a single byte sum of all the other bytes in the 
record, including the two markers. The checksum is computed with end- 
around carry. As each byte is added into the sum, the carry bit is also 
added in. 

Partial Sum 
+ Data Byte 
+ Carry 



Result 
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1.2 TIMING 

1.2.1 INTER-RECORD GAP (IRG) 

As was mentioned in section 1.1 each record consists of 132 data 
bytes including the checksum byte. In order to distinguish one record 
from another, the cassette handler adds a Pre-Record Write Tone (PRWT) and 
Post-Record Gap (PRG). PRWT and PRG are both pure mark tone. The Inter- 
Record Gap (IRG) between any two records thus consists of the PRG of the 
first record followed by the PRWT of the second record. The layout of 
the records and gaps is as follows: 



I PRWT I MARKER | DATA I PRG I PRWT I MARKER I DATA I PRG I 

RECORD 1 _ RECORD 2 



1 .2.2 NORMAL IRG MODE & SHORT IRG MODE 

The length of PRWT and PRG are dependent upon the Write Open mode. 
There are 2 types of IRG modes: Normal IRG mode and Short IRG mode. 

When a file is opened the most significant bit of AUX2 specifies the 
mode. On subsequent output or input, the cassette handler executes the 
READ/WRITE in either mode based on the MSB of the AUX2 byte: 

7 0 

AUX2 I C | I | | | | | | 



C =1 indicates that the cassette is to be read/written in Short 

IRG mode. (Continuous mode) 
C =0 indicates Normal IRG mode. 

Normal IRG Mode : 

This mode is used for a READ interleaved with processing; i.e. the 
tape always comes to a stop after each record is read. If the computer 
"STOPS" the tape and gets its processing done fast enough, the next READ 
may occur so quickly that the cassette deck may see only a slight dip in 
the control line. 

Short IRG Mode : 

In this mode the tape is not stopped between records, either when 
being written or during readback. 

■ 

On readback, the program must issue a READ for each record before it 
passes the read head. The only common use of this mode so far is storage 
of BASIC programs in internal (tokenized) form where, on readback, BASIC 
has nothing more to do with the data than put it in RAM. The special 
BASIC commands "CSAVE" and "CLOAD" specify this mode. 
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There can be a potential problem with this. The software that writes 
the tape must allow long enough gaps, so the beginning of records are not 
missed on readback. 



1.2.3 TIMING STRUCTURE 

The timings for each of the inter-record gaps are as follows: 

NORMAL IRG PRWT = 3 seconds of mark tone. 
SHORT IRG PRWT =0.25 seconds of mark tone. 

NORMAL IRG PRG = Up to 1 second of unknown tones. 
SHORT IRG PRG = From 0 to N seconds of unknown tones, where N 

is dependent upon user program timing. 

Each record is written with the following timing: once the motor 
starts and the Pre-Record Write Tone (PRWT) is written, the duration of 
the tone depends on the above format. The record follows, then the 
Post-Write Gap (PRG) is written. The motor is then stopped for Normal 
mode, but continues writing mark for Short IRG mode. 

Note that for the Normal IRG mode, the tape will contain a section of 
unknown data because of stopping and restarting the motor. (Up to 1 second 
of travel is possible, depending on the cassette machine.) This unknown 
data may be garbage data left previously on the tape. 

> 

1.2.4 NOISY I/O FEATURE 

The Noisy I/O feature is useful for determining the success of 
reading the tape, particularly with CLOAD. Marks and spaces use different 
sound frequencies and one quickly learns the good and bad sounds the OS 
makes. 

1.3 FILE STRUCTURE 

A file consists of the following three elements: 

1) A 20 second leader of the mark tone. 

2) Any number of data records. 

3) End-Of-File. 

When the file is opened (output), the OS starts by writing a mark 
leader of 20 seconds, the OS then returns to the caller, but leaves the 
tape running and writing marks. 

The WRITE/READ timeout counter is set for about 35 seconds as the OS 
returns. If the timeout occurs before the first record is written, the 
tape will stop, leaving a gap between the open leader and the first record 
leader. 
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1.4 TAPE STRUCTURE 

There are 2 sides to each tape. Each side has 2 tracks, one for 
audio and the other one for digital recording. This way the tape can be 
recorded in both directions. Following is a flat view of the tape: 



////////AUDIO TRACK//////// LEFT TRACK 



SIDE 

A 

////////DIGITAL TRACK//////// RIGHT TRACK 



' ////////DIGITAi * TRACK//////// RIGHT TRACK 

SIDE 

B 

////////AUDIO TRACK//////// * LEFT TRACK 



Tapes are recorded in 1/4 track stereo format at 1 7/8 inches per 
second (IPS). Note that the Atari 800 utilizes a tape deck that has a 
stereo head configuration (not a single or mono type). 



1.5 CASSETTE BOOT 

The Cassette Boot program can be booted from the cassette at power up 
time as part of the system initialization. 

System initialization performs functions such as zeroing all of the 
hardware registers, clearing RAM, setting flags and so on. 

After all the resident handlers are brought in, if the 'START 1 key is 
pressed, the Cassette Boot request flag CKEY [004A] is set. If the 
Cassette Boot request flag is set, then a Cassette Boot operation is 
attempted. 

The following requirements must be met in order to boot from the 
cassette: 

1) The operator must press the 'START 1 key as power is applied to the 
system. 

2) A cassette tape with a proper boot format file must be installed 
in the cassette drive, and the 1 PLAY 1 button on the recorder must 
be pressed. 
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3) The cassette file must have been created in Short IRG mode. 

4) When the audio prompt occurs, the operator must press a key on the 
keyboard. 

If all of these conditions are met, the OS will READ the boot file 
from the cassette and then transfer control to the software that was read 
in. The Cassette Boot process is given in more detail below. 

1) READ the first cassette record to the cassette buffer. 



2) Extract information from the first 6 bytes. The first 6 bytes of 
a Cassette Boot file are formatted as shown below: 



IGNORED 



1st BYTE 



# OF RECORDS 



MEMORY ADDRESS 



TO START LOAD 



— 



— 



LO 



HI 



LO 



ADDRESS 



HI 



6th BYTE 



1ST BYTE: is not used by the Cassette Boot process. 

2ND BYTE: contains the number of 128 byte cassette records to be 
read as part of the boot process (including the record containing 
this information). This number may range from 1 to 255, with 0 
meaning 256. 

3RD and 4TH BYTES: contain the address (L0,HI) at which to start 
loading the first byte of the file. 

5TH and 6TH BYTES: contain the address (L0,HI) to which control 
is transferred after the boot process is complete. Pressing the 
[S/RESET] key will also transfer control to this address assuming 
that the boot process is complete. 

When step 2 is complete, the Cassette Boot program will have: 

A) saved # of records to boot. 

B) saved the load address. 

C) saved the initialization address in CASINI [02,03]. 
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3) Move the record just read to the load address specified. 

4) READ the remaining records directly to the load area. 

5) 3SR to the load address +6 where a multi-stage boot process may 
continue. The carry bit will indicate the success of the operation 

(carry set = error, carry reset = success) on return. 

6) JSR indirectly through CASINI for initialization of the application. 
The application should put its starting address into DOSVEC [OA, OB] 
during initialization, and then return. 

7) JMP indirectly through DOSVEC to transfer control to the application. 

Pressing the [S/RESET] key after the application is fully booted will 
cause steps 6 and 7 to be repeated. 
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CASSETTE APPLICATIONS 

This section covers how to utilize the Atari cassette system. 

2.1 HOW TO CONFIGURE THE CASSETTE SYSTEM 

Most serial bus devices have two identical connectors: one is a 
serial bus input and the other a serial bus extender. Using these connec- 
tors peripherals may be "Daisy Chained" simply be cabling them together in 
a sequential fashion like the following diagram: 



I T.V. I 



II II I I I SERIAL 

J L J L J L I ~ BUS 

II II I I I I CONNECTOR 

I 800 | | DISK I | DISK I I 410 I 
I I I DRIVE | | DRIVE I | | 

I I I I 

However, the cassette does not conform to the protocol of the other 
peripherals that use the serial bus. The cassette must be the last device 
on the serial bus because it does not have a serial bus extender connector 
as the other peripherals do. The lack of a bus extender assures that 
there is never more than one cassette drive connected to the system. The 
system cannot sense the absence or presence of the cassette drive, so it 
may be connected and disconnected at will. 

Whenever there is a need to open a cassette file for reading or 
writing, the user will have to follow the following instructions: 

INPUT (DATA FROM 410 TO 800): When the cassette is opened for input, 
a single audible tone is generated using the keyboard speaker. If 
the cassette is ready (power on, serial bus cable connected, tape 
cued to start of file), the user must depress the f PLAY f button on 
the cassette and any 800 keyboard key (except [BREAK]) to initiate 
tape reading. 

OUTPUT (DATA FROM 800 TO 410): When the cassette is opened for 
output, two separate audible tones are generated using the keyboard 
speaker. If the cassette is ready (as previously described), the 
user must simultaneously press the 1 PLAY 1 and 1 RECORD 1 buttons on the 
cassette, and then press any keyboard key (except [BREAK]) to initiate 
writing the tape. 
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2.2 SAVING AND LOADING DIGITAL PROGRAMS 
Concept : 

The following technique saves the digital data directly from the 
computer through its I/O port of either the 410 or the Atari Lab Machine 
which uses 1/4 inch tape recorded at 7 1/2 inches per second. 

FOR BASIC: 

FORMAT: CSAVE 

100 CSAVE 

This command is usually used in direct mode to save a 
RAM-resident program onto cassette tape. 1 CSAVE 1 writes 
the tokenized version of the program to the 410. 

FORMAT: CLOAD 

100 CLOAD 

This command can be used in either direct or deferred mode 
to read programs from cassette tape into RAM for execution. 



FOR ASSEMBLY LANGUAGE: 

SOURCE PROGRAM 

FORMAT: LIST#C: [ ,XX, YY] 

This command is used to write assembly source code. The 
items in the optional brackets [,XX,YY] mean to transfer 
only lines XX to YY to cassette. If line numbers are not 
provided the whole program is listed to cassette. 

FORMAT: ENTER#C: 

This command reads source code from the cassette. 

OBJECT PROGRAM 

FORMAT : SAVE#C :< XXXX , YYYY 

The contents of a block of memory, locations XXXX to YYYY, 
is saved onto cassette. 

FORMAT: L0AD#C: 

This command will load memory with the material that was 
previously saved. The range of memory locations that are 
filled will be the same as those given in the original save 
command. 
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2.3 SAVING DIGITAL PROGRAMS WITH AUDIO AS BACKGROUND 
Concept : 

This recording technique does not allow any program control over the 
audio. The audio plays purely as background to help time pass during the 
monotonous loading process. 

STEP 1: Follow the digital writing instructions indicated in 2.2 

for BASIC and Assembly programs; except, this time ATARI 
standard cassette tape (1 7/8 inches per second) is not 
used. Because it is hard later for an individual to record 
audio onto 410, we have to use the ATARI recording lab 
machine, which uses 7 1/2 inches per second master tape. 
The lab machine is a much more sophisticated recording 
machine able to record data onto a specified track. 

On the lab machine, the recording mode is switched to "ON" 
for the right track, so digital is saved onto the right 
track of the 7 1/2 inch tape. 

STEP 2: Do STEP 1 for audio recording, except first rewind the tape 

to the beginning of the program then switch the recording 
mode to "ON" for left track. This way the audio is recorded 
onto the left track of the 7 1/2 inch tape. 



2.4 DIGITAL PROGRAMS, AUDIO, SYNC MARK, AND SCREEN MANAGEMENT 

Sync Mark Concept : 

There is no efficient way for the program to detect an audio segment 
when the cassette is playing. In order to solve the synchronization 
problem, Sync Mark is used to carry the signal to inform the program that 
an audio segment has been played (an audio segment can be either a piece 
of music or an instruction, depending on the application). 

More precisely, since audio data has no record structure, Sync Mark 
recorded on the digital track is more or less like End-Of-Record Mark for 
audio. For example, once the program senses the Sync Mark, the program 
can decide what to do next like stop the cassette motor for lengthy 
processing, or continue to play the next audio segment. 

STEP 1: The programmer figures out an audio script for "FROG". The 

script is like this: 

(MUSIC) TODAY I AM GOING TO TELL YOU A FAIRY-TALE NAMED 
"THE PRINCESS AND THE FROG". IT IS A SWEET STORY SO DON'T 
GO AWAY. / 

(MUSIC) BEFORE I START MY STORY, I WOULD LIKE TO KNOW WHO 
I AM TALKING TO. WHAT IS YOUR NAME? TYPE YOUR NAME AND 
HIT CARRIAGE RETURN. (PAUSE) 
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(MUSIC) NOW, LET'S START THE STORY. ONCE UPON A TIME, 
THERE WAS THIS BEAUTIFUL PRINCESS LIVING IN A CASTLE AND 
HER NAME WAS YYYY. / 

(MUSIC) ON A CLEAR AND BEAUTIFUL DAY, THE PRINCESS WAS 
WALKING ALONG THE / 

REMARK : 

- "/" means the program is checking for a sync mark. 
It is best if the speaker pause about 1/2 second here 
before continuing to the next segment of the audio 
script. 

- "PAUSE" is to indicate that the speaker pauses about 
1 second here to allow time for the stopping and 
starting of the cassette motor. Each audio segment 
should be at least 10 to 30 seconds long, because too 
many closely spaced Sync Marks can confuse the computer. 

STEP 2: It is suggested that before coding begins, the programmer 

draft a general plan for the program indicating the rela- 
tionship between screen (CPU) and audio. 

EXAMPLE: The following example (see page 111-13) illustrates 
how a programmer should create a cassette containing a 
program which has control over an audio track. The example 
is called "FROG": 

STEP 3: The programmer can start coding the program called 

"FROG", and it will look something like this: 

10 REM PROGRAM "FROG" TO DEMONSTRATE SYNCHRONIZATION 
20 REM OF AUDIO WITH DIGITAL FOR THE CASSETTE SYSTEM 
30 REM 

40 DIM IN$(20) 

50 POKE 5401 8, 52: REM TURN ON MOTOR 
60 GRAPHICS 1 

70 PRINT #6; "THE PRINCESS AND THE FROG" : PRINT #6; REM 

SET UP THE SCREEN FOR EVENT 2. 
80 GOSUB 1000: REM CHECK SYNC MARK, MAKE SURE THE INTRODUCTION 

IS SAID. 

100 POSITION X,Y:PRINT #6;"Y0UR NAME?" : REM FOR EVENT 4 
105 GOSUB 1000: REM EVENT 5 

110 POKE 5401 8, 60: REM STOP MOTOR FOR USER INPUT 
120 INPUT IN$:REM WAIT FOR THE USER'S NAME 
130 POKE 54018,52 

135 PRINT #6,CHR$(125):REM CLEAR THE SCREEN 

140 POSITION X,Y:PRINT #6;IN$:PRINT #6; :REM DISPLAY 

SCREEN FOR EVENT 10 
150 GODUB 1000: REM MAKE SURE SPEECH FOR EVENT 10 IS FINISHED 
160 PRINT #6; :REM READY FOR EVENT 12 
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FROG" 



FVFNT 


ai in t n 


SCREEN 


CHECK 
SYNC MARK 


MOTOR 1 
MODE I 


! 1 




1 




ON 1 


I 2 I 
I I 
I I 


'TODAY I AM' | 

•GOING TO..' I 

I 
I 


1 

1 1 1 
I THE PRINCESS 1 I 

I & THE FROG I | 

1 1 ! 
I GRAPHIC | 


1 

1 

1 
1 

1 


1 

1 

1 

1 


I 3 


I 




YES 




I 4 I 

I I 

I I 
i i 


— ... j 

BEFORE I ' I 

I ' I 

I 

I 


1 1 1 
I THE PRINCESS I 1 
I & THE FROG I 1 

1 PRAPUTP 

lYOUR NAME7XXXX I 


i 
i 

i 

1 


1 

1 1 

1 1 
1 


I 5 






YES 




I 6 








STOP I 


I 7 




1 WAIT TILL AN 

TMPIIT TC; 
llNru 1 1j 

RECOGNIZED 


1 

# 


1 1 
1 1 


I 8 








START I 


I 

I Q 




PI FAR TMF <^PRFFM 






I 10 

i 


I 'NOW LET'S ' 

i 


II 1 ! 

I 1 YYYY 

| AAA A J 

I GRAPHIC I 


i 
i 


1 1 

1 1 

1 1 


I 11 






YES 




I 12 


I 'ON A CLEAR..' 


1 1 1 
I GRAPHIC I 


1 


1 1 


I 13 
I 


I 
I 


1 
1 


1 
1 


1 1 
1 1 
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ROUTINE TO CHECK SYNC MARK: On the tape, non-sync is 
represented by "MARK" and Sync Mark is represented by 
"SPACE" • (Space is a "0" frequency, it is a lower pitch 
sound than a Mark which is a "1" frequency. As mentioned 
before, Mark frequency is 5327 Hz, Space is 3995 Hz). The 
Check Sync Mark routine continuously watches for a "SPACE" 
from the serial port. The routine looks like this: 

1000 IF INT(PEEK(53775)/32+0.5)=INT(PEEK(53775)/32) 
THEN RETURN: REM CHECK THE 5TH BIT OF EACH 

INCOMING BYTE. IF IT IS "0"THEN 
THE SYNC SPACE IS FOUND. 

1010 GOTO 1000 

ROUTINE TO CONTROL THE MOTOR: The program can turn the 
cassette motor on and off by poking location 54018 with the 
data given below: 

ON: POKE 54018,52 
OFF: POKE 54018,60 

STEP 4: After the audio script has been roughly written, the 

programmer should estimate the time and the tape length 
required for the designed audio script (including pauses) 
and program. If the tape length required is too long for 
one cassette, then either the script or the program will 
have to be modified to fit into one cassette. 

STEP 5: Save the program to a master tape, for example "MASTER 1". 

STEP 6: With the audio script the voice is taped with pauses on 

another master tape, "MASTER 2". 

STEP 7: After "MASTER 1" and "MASTER 2" are produced, these 2 

master tapes are merged to produce another master tape 
called "MASTER 3". "MASTER 3" has the program recorded 
first, and the audio spliced on the end. Three recording 
lab machines are needed for this procedure. Make 2 copies 
of "MASTER 3". 



STEP 8: Load the Sync Mark program into the Atari 800. The 

purpose of this program is to write continuous Sync Mark 
("0" frequency) onto the digital track. The Sync Mark 
informs the program that an audio segment has been played. 
Whenever there is a pause indicated on the audio script, 
a Sync Mark is needed at that place. The finished tape 
with audio and sync would be as follows: 
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TODAY. I AM... BEFORE I... NOW LET'S... 

' i 7/7/7/7/7/ i i 7/7/7/7/7/77/77/7/ i " " i 7/7/7/77/ 'audio 



SIDE I 
A AUDIO SEGMENT 



I//I I//I DIGITAL 

SYNC MARK 



SIDE 

B TAPE MOTION 



The Sync Mark program looks like this: 

10 REM PUSH "START" CONSOL KEY TO 
20 REM ADD THE SYNC MARK ONTO THE TAPE 
30 REM 
40 REM 

50 10=53760 : C0NS0LE=53279 : CASS=54018 
100 FOR 1=0 TO 8 
110 READ 3 : POKE 10+1,3 
120 NEXT I 

125 REM THE FOR LOOP SETS THE AUDIO FREQUENCY & CHANNEL 
130 DATA 5,160,7,160,5,160,7,160,0 
140 REM 

150 REM I/O IS SETUP; NOW START THE CASSETTE 
160 POKE CASS, 52 
200 POKE CONSOLE, 8 

210 IF PEEK(CONSOLE) <> 7 THEN 230:REM C0NS0LE=7 MEANS WRITE 
MARK, 

220 POKE 10+15,11: GOTO 200: REM CONSOLER KEYS NOT PRESSED 
230 POKE 10+15,128+11: GOTO 200: REM IF CONSOLE <> 7 WRITE 
"SPACE" 

STEP 9: Mount both "MASTER 3" tapes in two independent recording 

machines and rewind both tapes to the splice of program and 
audio. Configure one recording machine to one Atari 800 
with Sync Mark program loaded. This recording machine is 
prepared for recording Sync Mark on the digital track. The 
other recording machine will play back the audio recorded 
earlier. 

STEP 10: Type "RUN" to start the Sync Mark program. At the same 

time start the recording machines, one for recording, 
another one for playback. Listen to the audio and hit the 
"START" key whenever it is indicated by a pause in the 
audio script. 
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STEP 11; Now the tape is done, with the program recorded followed by 

the audio and Sync Mark recording. The finished tape is 
ready for mass production. 

2.5 DISABLING THE BREAK KEY 

It is suggested that the programmer disable the BREAK key. This 
prevents the cassette program from failing then the user accidently hits 
"BREAK". The OS will not recover a partial record, unless the user can 
rewind to the lost record. The disable BREAK key routine looks like 
this: 

4000 X= PEEK06): IF X 128 THEN 4020 
4010 POKE 16,X-128: POKE 53774, X-128 
4020 RETURN 

The disable routine should be called whenever there is a change of 
graphics mode or any screen open call. 



2.6 MASS PRODUCTION 

The programmer produces one or more "MASTER TAPES" according to the 
recording techniques discussed in sections 2.2, 2.3, and 2.4. All Atari 
Masters are recorded on open reel 1/4 track, 1/4 inch tape recorded at 7 
1/2 inches per second. The "MASTER TAPE" is supplied to the duplicator 
as a "SOURCE MASTER". 

The duplicator will take the "SOURCE MASTER" to make a "WORK MASTER" 
for the final cassette mass production. The released product will be 
third generation from the original. The following is a flow of the 
process: 



INTERIM^ ( WORK ^ MASS PRODUCTION 

A — ►[ ^MASTER J ^MASTER J H ^MASTER^ j — ► OF CASSETTES 



"INTERIM MASTER" is recommended for the duplicator, because the "WORK 
MASTER" may be destroyed or worn from excessive use. The "SOURCE MASTER" 
should be reserved only for emergency need. The "INTERIM MASTER" is the 
backup copy for the "WORK MASTER". 

2.6.1 MASS PRODUCTION OF CASSETTES 

At present, ATARI prefers the "BIN LOOP" method for mass production: 
The "WORK MASTER" is copied to produce a "LOOP MASTER". The LOOP MASTER 
may be on 1/4", 1/2", or any tape width. The BIN LOOP is spliced into a 
CONTINUOUS LOOP with a short clear leader at the splice. It is placed in 
a high-speed loop master machine which has one or more "SLAVE" machines. 
The configuration is like this: 
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MASTER MACHINE 



SLAVE MACHINES 



READ 
HEAD 



I I 

10 0 1 

[] l== 

I I 



I 

0 0 I 

[] I* 
I 



I I 
10 0 1 

==l [] l=- 
I I 



I I 

10 0 1 

=1 [] 
I 



ri 
I I 
I 

I.*. LOOP MASTER 

I 

I I 
' I 
I I 



The "LOOP MASTER" is repeatedly read. If the duplicator wants to 
produce 100 cassettes, for example, the length of the tape on the "SLAVE 
MACHINE" is measured to the length of the program multiplied by 100. 
There is a counter on the "MASTER" machine and it is set to 100. 



As the "LOOP MASTER" is continuously read, the data (all four tracks) 
is copied onto the "SLAVE MACHINE" tape. 



As the clear section in the LOOP MASTER is sensed, the "MASTER" 
machine produces a "CUTTING TONE" which is recorded on one or more tracks 
on the SLAVE MACHINE tapes. The counter will then increase by one. 

Each finished tape from the "SLAVE MACHINE" has 100 recorded programs 
with 100 CUTTING TONES recorded. It is fed into an automatic loading 
machine which winds the tape into C-Zero cassette shells. The configuration 
is like this: 



LOADER 



TAPE FROM 
SLAVE MACHINE 




CASSETTE TAPE HUBS 
CASSETTE SHELL 
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The cassette shells come with a small loop of leader which is bound 
to the cassette tape hubs. The loader pulls the leader from the shell, 
cuts it, and splices the end of the slave machine tape to the leader. The 
tape hub is used to wind the tape into the shell until the cutting tone is 
sensed. The slave machine tape is then cut and spliced to the leader on 
the other hub. 

The cassette shell is removed either manually or mechanically from 
the loader and the tape in the cassette shell is fully wound. The next 
cassette shell is loaded by the same process. 



2.6.2 QC TESTING 

Any time that a production run is created, samples must be taken from 
it and verified before it is approved and released. 

The QC testing is done normally by taking the first and the last 
cassette produced. Atari must receive at least 10 samples from each 
mass production for each master released. 
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This section discusses how to get multiple colors out of a single 
color graphics mode through the use of television artifacts. 

The ANTIC modes with which this can be accomplished are 2,3, and 15 
ANTIC mode 2 corresponds to BASIC mode 0, ANTIC mode 15 is BASIC mode 8, 
and ANTIC mode 3 has no corresponding BASIC mode. Each of these modes has 
a pixel resolution of one half color clock by one scan line. They are 
generally considered to have one color and two luminances. With the use 
of artifacts, pixels of four different colors can be displayed on the 
screen in each of these modes. 

The term TV artifacts refers to a spot or "pixel 11 on the screen that 
displays a different color than the one assigned to it. 

A simple example of artifacts using the ATARI computer is shown by 
entering the following lines: 

GRAPHICS 8 
COLOR 1 
POKE 710,0 
PLOT 60,60 
PLOT 63,60 

These statements will plot two points on a black background, however 
each pixel will have a different color. 

To understand the cause of these differing colors one must first 
understand that all the display information for the TV display is contained 
in a modulated TV signal. 

The two major components of this signal are the luminance, or bright- 
ness, and the color, or tint. The luminance information is the primary 
signal, containing not only the brightness data but also the horizontal 
and vertical syncs and blanks. The color signal contains the color 
information and is combined or modulated into the luminance waveform. 

The luminance of a pixel on the screen is directly dependent on the 
amplitude of the luminance signal at that point. The higher the amplitude 
of the signal, the brighter the pixel. 

The color information, however, is a phase shifted signal. A phase 
shifted signal is a constantly oscillating waveform that has been delayed 
by some amount of time relative to a reference signal, and this time delay 
is translated into the color. 

The color signal oscillates at a constant rate of about 3.579 MHz, 
thus defining the highest horizontal color resolution of a TV set. This 
appears on the screen in the form of 160 visible color cycles across one 
scan line. (There are actually 228 color cycles including the horizontal 
blank and sync, and any overscan.) 
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The term "color clock" refers to one color cycle and is the term 
generally used throughout the ATARI documentation to describe units of 
measurement across the screen. The graphics mode 7 is an example of one 
color clock resolution, where each color clock pixel can be a different 
color. (There are microprocessor limitations though.) 

ATARI also offers a "high resolution" mode (GRAPHICS 8) that displays 
320 pixels across one line. This is generated by varying the amplitude of 
the luminance signal at about 7.16 MHz, which is twice the color frequency. 

Since the two signals are theoretically independent, one should be 
able to assign a "background" color to be displayed and then merely vary 
the luminance on a pixel by pixel basis. This in fact is the way mode 8 
works, the "background" color coming from play field register 2, and the 
luminances coming from both play field registers 1 and 2. 

The problem is that in practice the color and lumincance signals are 
not independent. They are part of a modulated signal that must be demodu- 
lated to be used. Since the luminance is the primary signal, whenever it 
changes, it also forces a change in the color phase shift. For one or 
more color clocks of constant luminance this is no problem, since the color 
phase shift will be unchanged in this area. However, if the luminance 
changes on a half color clock boundary it will force a fast color shift at 
that point. Moreover, that color cannot be altered from the transmitting 
end of the signal (the ATARI computer). 

Since the luminance can change on half color clock boundaries, this 
implies that two false color, or artifact pixel types can be generated. 
This is basically true. However, these two pixels can be combined to form 
two types of full color clock pixels. This is illustrated below: 

TV Scan Line | 1 color | | 

I clock *| | 

L i J I I I 

I plx^tl | | | 



Luminance 
0=off 
1=on 



r 



0 


1 


0 


0 


1 


0 


0 


0 


1 


1 


0 


0 


0 


1 


1 


0 



I 



1/2 cc pixel color A 
1/2 cc pixel color B 
1 cc pixel color C 
1 cc pixel color D 



Note that each of these pixels requires one color clock of distance 
and therefore has a horizontal resolution of 160. 

The colors A through D are different for each TV set, usually because 
the tint knob settings vary. Thus they cannot be described as absolute 
colors, for example red; but they are definitely distinct from each other, 
and programs have been written that utilize these colors. 
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To illustrate a simple application of artifacting, refer to the 
example below. This program draws lines in each of the four artifact 
colors and then fills in areas using three of the colors. (Note that 
displaying many pixels of either type C or D next to each other results in 
the same thing: a line or constant luminance with background color.) 

The POKE 87,7 command causes the OS to treat this mode as mode 7 and 
to use two-bit masks when setting bits in the display memory. To generate 
color A, use COLOR 1, color B uses COLOR 2, and color C uses COLOR 3. 
Color D is generated by displaying COLOR 1 to the left of COLOR 2. 



10 GRAPHICS 8:P0KE 87,7:P0KE 710,0:P0KE 709,14 

20 COLOR 1:PL0T 10,5:DRAWT0 10,70 

30 PLOT 40,5:DRAWT0 40,70 

40 COLOR 2: PLOT 20,5:DRAWT0 20,70 

50 PLOT 41,5:DRAWT0 41,70 

60 COLOR 3: PLOT 30,5:DRAWT0 30,70 

70 FOR X=1 TO 3:C0L0R X:P0KE 765, X 

80 PLOT X*25+60,5:DRAWTQ X*25+60,70 

90 DRAWT0 X*25+40,70:P0SITIQN X*25+4Q,5 

100 XI0 18,#6,12,0,"S:" 

110 NEXT X 
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OOOO 
DDB6 
DA60 
0482 
DDA7 
D8E6 
00F3 
D800 
00F2 
0580 

009B 
0009 
0005 
E456 
0342 
0344 
0348 



20 

30 FMOVE 
40 FSUB 
50 FTEMP 
60 FSTOR 
70 FASC 
80 INBUFF 
85 AFP 
90 CIX 
0100 LBUFF 
0110 ; 
0120 CR 
0130 PUTREC 
0140 GETREC 
0150 CIOV 
0160 ICCOM 
0170 ICBAL 
0180 ICBLL 
0190 i 
0200 ; 



$4000 

SDDB6 
$DA60 
$0482 
$DDA7 
$D8E6 
$00F3 
$D800 
$00F2 
$0580 



ARBITRARY STARTING POINT 



0210 
0220 



$9B 
$09 
$05 
$E456 
$0342 
$0344 
$0348 

WRITTEN BY CAROL SHAW 

FLOATING POINT (F.P.) ROUTINE DEMO PROGRAM. 
READS TWO NUMBERS FROM SCREEN EDITOR, 
CONVERTS THEM TO FLOATING POINT. 
SUBTRACTS THE FIRST FROM THE SECOND, 
STORES THE RESULT IN FTEMP (USER- 







0230 


• 
9 


DEFINED F.P. REGISTER), AND DISPLAYS THE RESULT. 






0240 


• 
9 




• 






0250 


START 


1 


4000 


205340 


0260 




JSR 


GETNUM ;GET 1ST NUMBER FROM E: 

AND CONVERT TO F.P. 


4003 


20B6DD 


0270 




JSR 


FMOVE ;MOVE NUMBER FROM FRO TO FR1 


4006 


205340 


0280 




JSR 


GETNUM ;GET 2ND NUMBER FROM E: 

— OMIT IF ONLY ONE ARGUMENT 


4009 


2060DA 


0290 




JSR 


FSUB ;FRO <— FRO - FR1 

CHANGE TO GET DIFFERENT ROUTI 


400C 


900A 


0300 
0310 


• 
9 


BCC 


NOERR ;SKIP IF NO ERROR 






0320 


. 
9 


ERROR — 


DISPLAY MESSAGE 






0330 


• 
9 






400E 


A981 


0340 




LDA 


#ERRMSG&255 


4010 


8D4403 


0350 




STA 


ICBAL 


4013 


A940 


0360 




LDA 


#ERRMSG/256 


4015 


4C3940 


0370 




J MP 


CONTI N 






0380 


NOERR 




4018 


A282 


0390 




LDX 


#FTEMP&255 ; STORE RESULT IN 

FTEMP (USER'S F.P. VAR) 


401 A 


A004 


0400 




LDY 


#FTEMP/256 


401 C 


20A7DD 


0410 




JSR 


FSTOR 



0420 ; 

0430 ; CONVERT NUMBER TO ASCI I STRING. 







0440 


; FIND END 
POSITIVE 


OF STRING AND CHANGE NEGATIVE # TO 
AND ADD CARRIAGE RETURN. 






0450 


• 






401 F 


20E6D8 


0460 


JSR 


FASC 


; CONVERT FROM F.P. TO 
ASCI 1 STRING IN LBUFF 


4022 


AOFF 


0470 
0480 


LDY 

MLOOP 


#$FF 




4024 


C8 


0490 


I NY 






4025 


B1F3 


0500 


LDA 


(INBUFF) 


,Y ;LOAD NEXT BYTE 

(POINTED TO BY INBUFF). POSITIVE? 


4027 


10FB 


0510 


BPL 


MLOOP 


;YES. CONTINUE 


4029 


297F 


0520 


AND 


#$7F 


;N0. NEGATIVE — MASK OFF MSB IT 


402B 


91 F3 


0530 


STA 


(INBUFF) 


,Y 


402D 


C8 


0540 


1 NY 






402E 


A99B 


0550 


LDA 


#CR 


; STORE CARRIAGE RETURN 


4030 


91 F3 


0560 
0570 


STA 


(INBUFF) 








0580 


: DISPLAY RESULT 








0590 








4032 


A5F3 


0600 


LDA 


1 NBUFF 


; BUFFER ADDRESS IS IN INBUFF 


4034 


8D4403 


0610 


STA 


ICBAL 




4037 


A5F4 


0620 
0630 


LDA 

CONTIN 


1 NBUFF+1 




4039 


8D4503 


0640 


STA 


ICBAL+1 




403C 


A909 


0650 


LDA 


#PUTREC 


; COMMAND IS PUT RECORD 


403E 


8D4203 


0660 


STA 


ICCOM 




4041 


A928 


0670 


LDA 


#40 


; BUFFER LENGTH = 40 


4043 


8D4803 


0680 


STA 


ICBLL 




4046 


A900 


0690 


LDA 


#0 




4048 


8D4903 


0700 


STA 


ICBLL+1 




404B 


A200 


0710 


LDX 


#0 


;I0CB # = 0 (SCREEN EDITOR) 


404D 


2056E4 


0720 


JSR 


CIOV 


;CALL CIO 


4050 


4C0040 


0730 


J MP 


START 


;D0 IT AGAIN 
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I 



0740 ; 

0750 ; GETNUM — GET ASCI I STRING FROM E: AND 
CONVERT TO F.P. IN FRO 

0760 ; 
0770 GETNUM 



405.5 


A905 


0780 


LDA 


#GETREC 


;GET RECORD (ENDS IN CR) 


4055 

▼ ^0 


80 4203 


0790 


STA 


ICCOM 




4058 


A980 


0800 


LDA 


#LBUFF&255 


; BUFFER ADDRESS = LBUFF 


405A 


804403 


0810 


STA 


ICBAL 




405D 


A905 


0820 


LDA 


#LBUFF/256 




405F 


8D4503 


0830 


STA 


ICBAL+1 




4062 


A928 


0840 


LDA 


#40 


; BUFFER LENGTH = 0 


4064 


804803 


0850 


STA 


ICBLL 




4067 


A900 


0860 


LDA 


#0 




4069 


8D4903 


0870 


STA 


ICBLL+1 




406C 


A200 


0880 


LDX 


#0 


;IOCB # = 0 (SCREEN EDITOR) 


406E 


2056E4 


0890 


JSR 


CIOV 


;CALL CIO 


4071 


A980 


0900 


LDA 


#LBUFF&255 


; STORE BUFFER ADDRESS 












IN POINTER (1 NBUFF) 


4073 


85F3 


0910 


STA 


1 NBUFF 




4075 


A905 


0920 


LDA 


#LBUFF/256 




4077 


85F4 


0930 


STA 


1 NBUFF+1 




4079 


A900 


0940 


LDA 


#0 


; BUFFER INDEX ■ 0 


407B 


85F2 


0950 


STA 


CIX 




407D 


4C00D8 


0960 


J MP 


AFP 


;CALL ASCI 1 TO FLOATING POINT AND 


RETURN 










4080 


60 


0970 IN IT 


RTS 




; POWER UP ROUTINE (DO NOTHING) 



4081 45 0980 ERRMSG .BYTE » ERROR", CR INDICATES CARRY SET 

ON RETURN FROM FP ROUTINE 

4082 52 

4083 52 

4084 4F 

4085 52 

4086 9B 

0990 * 

1000 \ ROUTINE START INFO 
1010 ; 

4087 1020 *■ $2E0 
02E0 0040 1030 .WORD START 
02E2 1040 .END 



FLOATING POINT ROUTINES 



NAME 



ADDRESS 



DESCRIPTION 




APPROXIMATE 
MAXI-TIME(usec) 



AFP 

Ml 1 




1 m5dl.±i lo r loatiny rOint 


1 3500 


FASC 


D8E6 

1 *J 1— U 


1 r iuaiiiiy ru-LiiL to HSC11 


950 


IFP 


D9AA 


T nf prior f-n PI nof i nn Dni 

I li it. t?yc i uu r JLuating rulrlL 


1 1330 


FPI 


D9H? 


I r coating roint to integer 


2400 


FSUB 


1 DA60 


| fro „ FRO - FR1 Subtraction 


I 740 


FADD 


1 DA66 


| fro „ FRO + FR1 Addition 


I 710 


FMUL 


1 DADB 


I FRO FRO * FR1 Multiplication 


I 12000 


FDIV 


1 DB28 


| FRO — FRO / FR1 Division | 


10000 


FLDOR 


1 DD89 


I Floating Load FRO using X,Y | 


70 


FLDOP 


1 DD8D 


I Floating Load FRO using FLPTR | 


60 


FLD1R 


1 DD98 


I Floating Load FR1 using X,Y 


70 


FLD1P 


1 DD9C 


I Floating Load FR1 using FLPTR | 


60 


FSTOR 


1 DDA7 


I Floating Store FRO using X,Y | 


70 


FSTOP 


DDAB 


I Floating Store FRO using FLPTR | 


70 


FMOVE 


DDB6 


| FRO — FR1 F.P. Move | 


60 


PLYEVL ! 


DD40 


I Polynomial Evaluation j 


88300 


EXP | 


DDCO 


j FRO 
FRO — e exponentiation 


11 5900 2: .1s 


EXP10 | 


DDCC 


I FRO — 10^"^ exponentiation | 


108800 


LOG 


nrrn 


i r r\u — — LUbgUKUj natural log 


136000 


LOG1Q 


DFD1 

L> l_ L/ 1 


FRn — — 1 nn ( FRH ^ onmmnn Inn 1 

r nu i_uu^Q\rr\Uy common log 


1Zj4UU 


7Pnn 1 

Zr RO 


DA44 


r— r-\ /—» t~\ ■ 

FRO — 0 


80 


AF1 | 


DA46 


I clear page zero F.P. reg. (6 bytes) | 


80 


In BASIC | 








Cartridge: | 








SIN | 


BDA7 


1 FRO — SIN(FRO) | 


79400 


COS | 


BDB1 


1 FRO — COS(FRO) | 


77400 


AT AN | 


BE77 


| FRO — ATAN(FRO) | 


126700 


SQR | 


BEE5 


1 FRO — SQUARE ROOT (FRO) | 


131100 



Times are for worst case, including 

JSR and RTS. 

Times are approximate. 

1 sec, = 1000000 usee. 
Times are approximately 30?o-40?o less 
with DMA disabled (SDMCR)s 

POKE 559,0 disable DMA 

POKE 559,34 enable DMA 
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APPENDIX VI - CIO 




I 

GET HANDLER ENTRY 




WRITE 



c 



OPEN 






A,Y =$81 


NO 




RETURN 





GET DEVICE 
NAME (ICBALZ) 



I 



GET ENTRY 
FROM HATABS 



IOCB ALREADY OPEN 



FOUND 

? 



NO 


A, Y = $82 




RETURN 



NON-EXISTENT DEVICE 



ICHIDZ=HATABS IND 
[CNNOZ=DEVICE NUMB 



;X 

;r 



1 



GET POINTER TO 
HATABS ENTRY 



T 



GET VECTOR TO 
HANDLER ENTRY 



I 



JSR (VECTOR) 



i 



FAKE PUTCHR TO 
SETUP ICPTL.ICPTH 



I 



RESTORE USER 
IOCB FROM ZIOCB 



I 



c 



Y=ERROR 

T~ 



RETURN 
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APPENDIX VII - QUME PRINTER HANDLER 



1 ; HANDLER USES THE FRONT PORTS TO SEND DATA TO A QUME PRINTER 

10 *=$3300 
20 CR=$9B 
30 SPCE=$20 
40 PIAB=$D301 
50 PIAC=$D303 
60 DOSVEC=$0A 
70 DOSINI=$0C 
80 HATABS=$031A 
90 MEML0=$2E7 
0100 ; 

0110 ; HANDLER ENTRY TABLE 
0120 ; 

0130 QHTBL .WORD QOPEN-1 
0140 .WORD QXIT-1 "CLOSE" 
0150 .WORD QERR-1 "GET" 
0160 .WORD QPUT-1 
0170 .WORD QXIT-1 "STATUS" 
0180 .WORD QXIT-1 "SPECIAL" 
0190 JMP OOPEN 

0200 QH00K1 LDA DOS INI I NIT ON LOAD 

0210 STA DOSLNK 
0220 LDA DOSINI+1 
0230 STA DOSLNK+1 

0240 QHOOO JSR QINST TRY TO INSTALL 

0250 BCC QH001 BY STEALING DOSINI 

026U RTS PASS RETURN 

0270 QH001 LDA #QH00K&255 

0310 STA DOSINI 

0320 LDA #QH00K/256 

0360 STA DOSINI+1 

0370 RTS RETURN TO DOS 

0380 QH00K2 JSR JIND FIRST I NIT DOS 
0390 JMP QHOOO THEN INSTALL US 

0400 JIND JMP (DOSLNK) I NIT DOS TOO 
0410 DOSLNK .WORD SE477 LNK FOR I NIT 
0420 PITCH .BYTE $80 
0430 VPTCH .BYTE $60 
0440 ACUH .WORD 0 
0450 SPACES .WORD 0 
0460 QWD .WORD 0 



VI 1-1 



I NIT QUME AND 
SOFTWARE VARIABLES 



0470 
0480 
0490 
0500 

0510 OOPEN LDA #0 
0520 LDX #5 

0530 Ql LP STA ACUH,X CLR VARS 
0540 DEX 
0550 BPL Ql LP 

0560 QSET LDA PI AC SET FRONT PORTS 

0570 AND #$FB 

0580 STA PI AC PT TO DDR 

0590 LDY #7 

0600 STY PIAB SET 3 OUT 

0610 ORA #4 

0620 STA PI AC 

0630 LDA #2 

0640 STA PIAB 

0650 BNE QSNDU RESTORE 

0660 ; 

0670 ; SEND A CONTROL WORD TO QUME 
0680 ; 

0690 SNDYA STY QWD-1 
0700 SNDA STA QWD 
0710 QSND LDA PIAB 
0720 AND #8 

0730 BNE QSND WAIT FOR RDY 

0740 QSNDU LDY #16 

0750 LDA QWD 

0760 EOR #7 

0770 STA QWD 

0780 QSLP LDA QWD 

0790 AND #1 

0800 ORA #2 

0810 STA PIAB 

0820 JSR QDELAY 

0830 AND #1 

0840 STA PIAB 

0850 JSR QDELAY 

0860 ORA #2 

0870 STA PIAB 

0880 LSR QWD+1 

0890 ROR QWD 

0900 DEY 

0910 BNE QSLP 

0920 JSR QDELAY 

0930 ORA #4 STROBE 

0940 STA PIAB 

0950 JSR QDELAY 

0960 AND #3 

0970 STA PIAB 

0980 RTS 



VI I- 



0990 
1000 
1010 
1020 
1030 
1040 
1050 
1060 
1070 
1080 
1090 
1100 
1110 
1120 
1130 
1140 
1150 
1160 
1170 
1180 
1190 
1200 
1210 
1220 
1230 
1240 
1250 
1260 
1270 
1280 
1290 
1300 
1310 
1320 
1330 
1340 
1350 
1360 
1370 
1380 



(ALWAYS) 
(NEGATE IT) 



DELAY FOR LINE SETTLING 



QDELAY LDX #60 
QDLPO DEX 

BNE QDLPO 

RTS 



SEND A CHARACTER FROM ACC 



QPUT CMP #CR 

BEQ OCR 

CMP #SPCE 

BCC RLY1 

BNE PUTPRT 

INC SPACES 
RLY1 BNE RLY2 
OCR LDA ACUH+1 

ORA #$40 

TAY 

LDA ACUH 

ORA #2 

JSR SNDYA 

LDA VPTCH 

ORA #3 

JSR SNDA 

LDA #0 

STA ACUH 

STA ACUH+1 

STA SPACES 
RLY2 JMP OX IT 
PUTPRT PHA 

LDX SPACES 

BEQ PPX 

LDA #0 

TAY 
PPLP CLC 

ADC PITCH 

BCC PPO 

I NY 



SEND TO QUME 
VERTICAL PITCH 

DO LINE FEED 



SAVE CHAR 



VI \-93 



1390 PPO DEX 

1400 BNE PPLP 

1410 PHA 

1420 STX SPACES 

1430 CLC 

1440 ADC ACUH 

1450 STA ACUH 

1 460 TYA 

1470 ADC ACUH+1 

1480 STA ACUH+1 

1 490 PLA 

1500 ORA #2 

1510 JSR SNDYA 

1520 PPX LDA #0 

1530 STA QWD+1 

1540 PLA GET CHAR BACK 

1550 ASL A 

156U BCC NOUND 

1570 LDY #5 

1 580 PHA 

1590 LDA #$F1 

1600 JSR SNDYA 

1610 PLA 

1620 CMP #SPCE+SPCE 

1 630 CLC 

1640 BNE NOUND 

1650 INC SPACES 

1660 JMP QXIT 

1670 NOUND ROL QWD+1 

1680 ASL A 

1690 ROL QWD+1 

1700 ASL A 

1710 ROL QWD+1 

1720 ASL A 

1730 ROL QWD+1 

1740 ORA #1 

1750 INC SPACES 

1760 JSR SNDA 

1770 QXIT LDY #1 

1780 RTS 



UNDERLINE IT INVERSE 
NOT A SPACE 



VI l-f H 



1790 
1800 
1810 
1820 
1830 
1840 
1850 
1860 
1870 
1880 
1890 
1900 
1910 
1920 
1930 
1940 
1950 
1960 
1970 
2010 
2020 
2060 
2070 
2110 
2120 
2160 
2170 
2180 
2190 
2200 



9 



9 



ERROR EXIT 



QERR LDY #$8B 
RTS 



9 



9 



INSTALL HANDLER IN HATABS 



QINST LDY #0 
QINLP LDA HATABS, Y 

CMP #$50 FIND P: 

BEQ QIPUT 

I NY 

I NY 

I NY 

CPY #$21 
BCC QINLP 
RTS 

QIPUT LDA #QHTBL&255 

STA HATABS+1 ,Y 

LDA #QHTBL/256 

STA HATABS+2,Y 

LDA #QEND&255 

STA MEMLO 

LDA #QEND/256 

STA MEMLO+1 

CLC 

RTS 
QEND=* 

.END 



END OF TABLE? 
NO, LOOP 
ELSE RETURN 



SET MEMLOL 



SET MEMLOH 



VI l-«S 



RANDOM ACCESS 
by BIN Bart left 



DEFINITION OF RANDOM ACCESS 

Random access Is defined as any method of reading or writing records from/ to 
any part of a data file without first having to read through previous records 
of the file. 



Before any I/O command can be processed, the storage media must be physically 
positioned on the device to the correct byte location. A sequential device 
such as the ATARI 410 cassette tape drive must be positioned manually by the 
operator using the tape counter. Thus, if record 100 Is desired, the tape 
drive must first bypass records 1-99. It should be obvious that processing 
Is very time consuming simply because of the physical nature of the device. 

A random device such as the ATARI 810 disk drive can be positioned to any 
byte In a file under the control of a BASIC porgram. Thus If record 100 Is 
desired, the disk drive can position there immediately. Random access is 
accomplished In a BASIC program with the POINT command. 



OPEN #1,12,0,"D1: " 

SECT0R=63 
BYTE=26 

POINT #1, SECTOR, BYTE 



The above commands cause the file opened on channel 1 to be positioned to 
sector 63, byte 26. The file must have been previously opened in mode 12 and 
sector 63 must have been allocated to the file by the File Manangement System 
(FMS). 



GOALS 

1. Define a data file structure that facilitates random access. 

2. Maximize diskette utilization by using all available user space In a file. 

3. Simplify coding by developing subroutines to handle the most common random 
access processing. 



CONCEPTS 

1. Random access can be facilitated In 2 ways. 

First, store the sector and byte Information needed by the POINT command In 
the data file so that It can be readily assigned to a program variable when 
the file Is opened. Second, have the program variable use as little RAM as 
poss ib le. 

A two-dimensional numeric array could be used as the program variable. 
However, each record would require 12 bytes of RAM. A string variable will 
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RANDOM ACCESS 



use less RAM because the sector number ranging 0-720 can be stored In 2 bytes 
and the byte offset ranging 0-127 can be stored In 1 byte. 

2. Maximum diskette utilization Is accomplished by using mode 12 (I/O) 
Instead of mode 9 (append) In maintenance programs. 

There are 2 problems with using mode 9 to access a data file. First, when 
the OPEN command Is processed, the FMS will always allocate a new sector to 
the file regardless of whether the last sector Is completely filled with 
data. Second, the POINT command will not execute on a file opened In mode 9. 

Mode 12 Is facilitated by allocating blank records to the data file when It 
Is created. 

3. Record allocation Is facilitated by having a 1 byte status byte for each 
record. A value of 0 Indicates the record is not active. A value of 1 
Indicates the record Is active. 



FILE STRUCTURE 

A data file will consist of 3 sections. 

FILE HEADER RECORD 

FILE RANDOM ACCESS POINTERS 

DATA RECORDS 

The file header record Is the first sector of the file. It Is 125 bytes long 
(124 data + 1 del imiter). 

FILE HEADER RECORD 

BYTE CONTENTS 

1-2 sector address of file header record 

3 byte offset of file header record (0) 

4 not used 

5-6 # records In file 
7-8 # bytes in record 
9-124 not used 

The file random access pointers Immediately follow the file header record and 
thus start In the second sector of the file. The data is stored as a string 
variable consisting of groups of 4 bytes. The first 4 bytes are used to 
loacte the pointer strings own location In the file. Then there are 4 bytes 
for each record In the file. 

FILE RANDOM ACCESS POINTERS 

BYTE CONTENTS 

1-2 sector address of file random access pointers 

3 byte offset of file random access pointers 

4 not used 
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5-N 4 bytes for each record 

1-2 sector address of record 

3 byte offset of record 

4 status of record 

The data records Immediately follow the file random access pointers. They 
are stored as string variables 

RANDOM ACCESS SUBROUTI NES 
U FILEOPEN.SUB 

This routine opens a file In mode 12 and Initializes the random access 
variables used In the other routines. 

Input variables: 

FILES - must be dimensioned and assigned by the user (15 bytes) 
CHANNEL - IOCB number (1-5) 

Call: 

GOSUB 9300 

Output variables: 

FILEMAX - I records in file 

FILELEN - # bytes In record 

FILEPTRS - contains the random access pointers 

FILERECS - dimensioned for record I/O 

Scratch variables: 
FILESEC 

FILEBYT These are not currently used 
F I LESTS 



2. FILEADD.SUB 

This routine allocates the next available record by reading through FILEPTRS 
looking for a status byte of 0. When a status of 0 Is found, It Is set to 1 
and the record* Is stored In RECORD. If RECORD returns a value of 0, all 
records In the file are active. 

Input variables: 
none 

Call: 

GOSUB 9400 

Output variables: 

RECORD - record# of next available record 
FILEPTRS - updated with status byte of 1 
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Scratch variables: 
RECORD 1 
B 



3. F I LEDEL.SUB 

This routine flags a record Inactive by changing Its status byte In FILEPTRS 
to 0. 

Input variables: 
RECORD 



Call: 

GOSUB 9450 

Output variables: 

FILEPTRS - updated with status byte of 0 

Scratch variables: 
B 



4. FILEPTR.SUB 

This routine updates the random access pointer section of the data file with 
the current value of FILEPTRS. 

input variables: 
none 

Call: 

GOSUB 9500 

Output variables: 
none 

Scratch variables: 
S 
B 



5. FILEPOS.SUB 

This routine positions the file pointer to the beginning of a record. 

Input variables: 

RECORD - record# to point to. 

Cal I : 

GOSUB 9600 
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Output variables: 

STS - value of status byte for record 

Scratch variables: 
S 



9200 REM APPENDIX AND ROUTINES BY WILLIAM BARTLETT 
9300 REM »FILE0PEN.SUB» WBB 3-30-81 

9305 REM OPEN A FILE IN MODE 12 AND DEFINE ALL VARIABLES 
9310 OPEN #CHANNEL,12,0,FILE$ 
9315 DIM FILEHED$(124) 

9320 FOR 1=1 TO 124.-GET #CHANNE L , B : F I LEHED$ ( I ) =CHR$ ( B ) : NEXT I :GET #CHANNEL,B 
9325 FILESEC=ASC(FILEHED$(1))*256+ASC(FILEHED$(2)) 
9330 F I LEBYT=ASC ( F I LEHEDS ( 3 ) ) 
9335 FILESTS=ASC(FILEHED$(4)) 

9340 F I LEMAX=ASC ( F I LEHEDS ( 5 ) ) *256+ASC( F I LEHEDS ( 6 ) ) 
9345 F I LELEN=ASC( F I LEHEDS (7 ) ) *256+ASC(F I LEHEDS ( 8 ) ) 
9350 DIM F I LEPTRS ( 4+4*F I LEMAX ) , F I LERECS ( F I LELEN ) 

9355 FOR 1=1 TO 4+4*F I LEMAX : GET #CHANNEL,B:F I LEPTRS ( I )=CHR$(B) :NEXT I :GET 

#CHANNEL,B 

9360 RETURN 



9400 REM 'F I LEADD.SUB' WBB 3-30-81 

9405 REM ALLOCATE THE NEXT AVAILABLE RECORD 

9410 RE CORD =0 

9415 IF F I LEMAX=0 THEN RETURN 
9420 FOR RECORD1=1 TO F I LEMAX 
9425 B=RECORD 1*4+4 
9430 IF FILEPTRS(B,B)=CHRS(0) THEN 

REC0RD=REC0RD 1 : RECORD 1 =F I LEMAX : F I LEPTRS (B,B) =CHR$ ( 1 ) 
9435 NEXT RECORD 1 
9440 RETURN 



9450 REM 'F I LEDEL.SUB' WBB 3-30-81 

9455 REM DELETE AN ACTIVE RECORD 

9460 B=REC0RD*4+4 

9465 FILEPTR$(B,B)=CHR$(0) 

9470 RETURN 
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9500 REM 'F I LEPTR.SUB* WBB 3-19-81 
9510 REM WRITE F I LEPTR$ 

95 1 5 S=ASC(F I LEPTRS ( 1 ) ) *256+ASC ( F I LEPTR$ ( 2 ) ) 
9520 B=ASC(FILEPTR$(3)) 
9525 POINT #CHANNEL,S,B 

9530 FOR 1=1 TO 4+4*F I LEMAX:B=ASC(F I LEPTRS ( I ) ) :PUT #CHANNEL,B:NEXT I 
9535 RETURN 



9600 REM »FILEPOS.SUB» WBB 3-31-81 
9605 REM POINT FILE TO RECORD 

9610 S=ASC(FILEPTR$(REC0RD*4+1 ) )*256+ASC(F I LEPTRS (REC0RD*4+2) ) 
9615 B=ASC( F I LEPTRS ( REC0RD*4+3 ) ) 
9620 STS=ASC(FILEPTR$(REC0RD*4+4)) 
9625 POINT #CHANNEL,S,B 
9630 RETURN - 



I. INTRODUCTION TO FILE001 

This program Is used to create a new disk data file, allocate Its file space, 
and Initialize Its random access structure. The random access structure Is 
designed to Interface with the following BASIC subroutines. 

FILE0PEN.SUB 
F I LEADD.SUB 
FILEDEL.SUB 
F I LEPTR.SUB 
FILEP0S.SUB 

II. PROGRAM STRUCTURE 

0001-0999 main line logic 
1000-9999 subroutines 

III. PROGRAM LOGIC The 5 major execution phases are program Initialization, 
file definition, screen setup, file allocation, and closing. 

A. Initialization 1000-1495 

1015 dimension variables 

1020 Identify program to user 

1025-1035 allow user to exit program 

1040 set up BLANKS to be used as a string fll ler 

B. File Definition 1500-1999 

1510-1535 have user define parameters of file 
1540-1550 allow user to redefine parameters until correct 
1600-1645 search diskette dlrcetory to Insure that the file specified 

doesn't already exist 
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1700-1730 verify there are enough free sectors to create the file 
1800-1825 concatenate the filename 

C. Screen setup 9600-9650 

D. FI le Al location 2000-2499 



2370-2375 send final FILEPTRS to file 
E. Closing 0900-0999 



10 REM 'FILE0001' WBB 3-12-81 

100 REM MAIN LINE 

110 G0SUB 1000 

120 IF YN$="N" THEN 900 

130 G0SUB 1500 

140 GOSUB 9600 

150 GOSUB 2000 

900 REM END 

910 CLOSE #1 

920 GRAPHICS 0 

930 END 

1000 REM IN IT 

1005 TRAP 9800 

1010 GRAPHICS 2 

1015 DIM YN$(1),DVC$(3),FILE$(8),EXT$(3),FILENAME$(15),FMS$(16),BLANK$(128) 

1020 PLOT 5,4:PRINT #6;"F I LE0001 " 

1025 PRINT "THIS PROGRAM INITIALIZES A NEW FILE." 

1030 PRINT "DO YOU WISH TO PROCEED (Y/N) »»; 

1035 INPUT YN$ 

104U BLANK$=" ":BLANK$( 128)=" ": BLANKS ( 2) =BLANK$ 

1095 RETURN 

1500 REM DEF FILE 

1505 GRAPHICS 2 

1510 PRINT #6; "FILE DEFINITION" 

1515 PRINT " DEVICE ";: INPUT DVC$:DVC$(LEN(DVC$)+1 )=":" 
1520 PRINT " FILE NAME ";: INPUT FILES 
1525 PRINT " EXTENT I ON ";: INPUT EXT$ 



2005 
2010 
2015 




2100-2180 
2200-2245 
2305 



2310-2345 
2350 



2355 
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1530 PRINT " # RECORDS •«;: INPUT F I LEMAX 

1535 PRINT "REC LENGTH ";: INPUT F HELEN 

1540 PRINT "DO YOU WISH TO PROCEED (Y/N) "; 

1545 INPUT YN$ 

1550 IF YN$<>"Y" THEN 1500 

1600 REM VERIFY FILE DOESNT EXIST 

1605 FMS$=DVC$:FMS$(LEN(FMS$)+1 )=••*.*» 

1610 OPEN #1,6,0,FMS$ 

1615 INPUT #1,FMS$ 

1620 IF FMS$(2,2)<>" THEN 1700 

1625 IF FMS$(3,2+LEN(FILE$)X>FILE$ OR FMS$( 1 1 , 1 0+LEN(EXT$) ) <>EXT$ THEN 1615 
1630 CLOSE #1 

1635 PRINT "FILE ALREADY EX I STS I " ; CHR$ ( 253 ) 
1640 GOSUB 9850 
1645 GOTO 1500 

1700 REM VERIFY ENOUGH DISK SPACE EXISTS 
1705 CLOSE #1 

1710 FREE=VAL ( FMS$ (1,3)): NEED=F I LEMAX* ( F I LELEN+5 )/ 1 25+1 
1715 IF NEED <F REE THEN 1800 

1720 PRINT "INSUFF FILE SP! " : PR I NT FREE;" FREE ";NEED;" NEEDED !";CHR$( 253) 
1725 GOSUB 9850 
1730 GOTO 1500 

1800 REM CONCATENATE FILENAME 
1805 F I LENAME$=DVC$ 

1810 F I LENAME$(LEN(F I LENAME$)+1 )=F I LE$ 
1815 F I LENAMES ( LEN ( F I LENAMES ) +1 ) =" . " 
1820 FILENAME$(LEN(FILENAME$)+1 )=EXT$ 
1825 RETURN 

2000 REM I NIT HEADER, PO I NTER, RECORD STRINGS 
2005 OPEN #1,8,0, FILENAMES 
2010 NOTE #1 ,FILESEC,FILEBYT 

2015 DIM F I LEHED$( 124) ,F I LEPTR$(4+4*F I LEMAX) ,F I LEREC$(F I LELEN) 

2100 REM FILE HEADER 

2105 F I LEHED$=BLANK$ 

2110 HI=INT(FILESEC/256) 

2115 LO=F I LESEC-H I *256 

2120 FILEHED$(1,1 )=CHR$(HI ) 

2125 FILEHED$(2,2)=CHR$(L0) 

2130 F I LEHEDS (3,3) =CHR$ ( F I LEBYT) 

2135 FILEHED$(4,4)=CHR$(0) 

2140 HI=INT(FILEMAX/256) 

2145 LO=F I LEMAX-H I *256 

2150 FILEHED$(5,5)=CHR$(HI ) 

2155 FILEHED$(6,6)=CHR$(L0) 

2160 HI=INT(FILELEN/256) 

2165 L0=FILELEN-HI*256 

2170 FILEHED$(7,7)=CHR$(HI ) 

2175 FILEHED$(8,8)=CHR$(L0) 

2180 PRINT #1 jF I LEHEDS 

2200 REM FILE POINTER 

2205 FOR 1=1 TO 4+4*FILEMAX STEP 1 28 : F I LEPTRS ( I ) =BLANK$ : NEXT I 
2210 NOTE #1,S,B 
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2215 HI=INT(S/256) 
2220 LO=S-H 1*256 
2225 FILEPTR$(1,1)=CHR$(HI) 
2230 FILEPTR$(2,2)=CHR$(L0) 
2235 FILEPTR$(3,3)=CHR$(B) 
2240 FILEPTR$(4,4)=CHR$(0) 
2245 PRINT #1;FILEPTR$ 
2300 REM RECORDS 

2305 FOR 1=1 TO FILELEN STEP 1 28 : F I LERECS ( I ) =BLANK$ : NEXT I 
2310 FOR 1=1 TO FILEMAX 
2315 NOTE #1,S,B 
2320 HI=INT(S/256) 
2325 L0=S-H 1*256 

2330 F I LEPTR$( 1*4+1 , 1*4+1 )=CHR$ (HI ) 
2335 F I L EPTR$ (1*4+2,1*4+2) =CHR$ ( LO ) 
2340 FILEPTR$( 1*4+3, 1*4+3 )=CHR$(B) 
2345 F I LEPTR$( 1*4+4, 1*4+4) =CHR$(0) 
2350 GOSUB 9700 
2355 PRINT #1 ;F I LERECS 
2360 NEXT I 
2365 CLOSE #1 

2370 OPEN #1,12,0, FILENAMES 
2375 GOSUB 9510 
2380 RETURN 
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9500 REM 'FILEPTR.SUB' WBB 3-19-81 
9510 REM WRITE FILEPTR 

9515 S=ASC(FILEPTR$(1,1 ) )*256+ASC(F I LEFTR$(2,2) ) 
9520 B=ASC(FILEPTR$(3,3)) 
9525 POINT #1,S,B 
9530 PRINT #1;FILEPTR$ 
9535 RETURN 

9600 REM DISPLAY SCREEN TEMPLATE 
9605 GRAPHICS 2 

9610 PRINT #6;"* INITIALIZING *" 

9615 PRINT #6 

9620 PRINT #6;"CURRENP' 

9625 PRINT #6;" TOTAL" 

9630 PRINT #6;" % COMP" 

9635 PRINT #6 

9640 PRINT #6;" SECTOR" 

9645 PRINT #6;" BYTE" 

9650 RETURN 

9700 REM REFRESH SCREEN 

9705 PLOT 10,2:PRINT #6; I 

9710 PLOT 10,3:PRINT #6;FILEMAX 

9715 PLOT 10,4:PRINT #6; I NT( l/F I LEMAX*100) 

9720 PLOT 10,6:PRINT #6;S;" " 

9725 PLOT 10,7:PRINT #6;B;" » 

9795 RETURN 

9800 REM TRAP. SUB 

9805 TRAP 9825 

9810 PRINT "ERROR ";PEEK( 195);" AT ";PEEK( 1 87)*256+PEEK( 1 86) 
9815 PRINT "ACKNOWLEDGE "; 
9820 INPUT YN$ 
9825 END 

9850 REM 'DELAY. SUB' WBB 3-19-81 

9851 REM DELAYS EXECUTION FOR 2.5 SEC 

9852 REM ( SCRATCH-P20 ) 

9860 P20=PEEK(20)+150: IF P20>255 THEN P20=P20-256 
9865 IF PEEK(20X>P20 THEN 9865 
9870 RETURN 
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EXAMPLE PROGRAM 



10 REM 'F ILEEX' WBB 3-31-81 

100 REM EXAMPLE OF RANDOM ACCESS ROUTINES 

101 REM THIS PROGRAM WILL PROCESS THE FILE D2: AREACODE.DAT 

102 REM WHICH SHOULD HAVE BEEN INITIALIZED USING 'FILE0001' 

103 REM IT CONSISTS OF 24 BYTE RECORDS: 1-3 AREA CODE, 4-24 LOCATION DESC 

104 REM 

110 GRAPHICS 0 

120 PRINT "'FILEEX'":PRINT :PRINT "INITIALIZING" 
200 REM INITIALIZE VARIABLES 
210 DIM FILE$(15),AC0DE$(3),L0C$(21),YN$(1) 
220 CHANNEL 3 1 

230 F I LE$="D1 : AREACODE.DAT" 
300 REM OPEN DATA FILE 
310 PRINT "OPENING DATA FILE" 
320 GOSUB 9300 

400 REM BEGIN OPERATOR INPUT 
410 PRINT 

420 PRINT " ( 0=END ) AREA CODE ";: INPUT ACODE$:IF ACODE$="0" THEN 900 
500 REM SEARCH ACTIVE RECORDS FOR MATCHING AREA CODE 
510 MATCH=0 

520 FOR RE CORD =1 TO FILEMAX 
530 GOSUB 9600 

540 IF STS=1 THEN GOSUB 5000 

550 NEXT RECORD 

560 IF MATCH=1 THEN 400 

600 REM MATCH NOT FOUND, ALLOW ADD 

610 PRINT "MATCH NOT FOUND IN FILE!" 

620 PRINT "(Y/N) DO YOU WISH TO ADD ";: INPUT YN$ 

630 IF YN$<>"Y" THEN 400 

700 REM ADD REQUESTED BY OPERATOR 

710 GOSUB 9400 

720 IF RECORD=0 THEN PRINT "FILE IS FULL, RECORD NOT ADDED !":GOTO 400 

730 PRINT "LOCATION: ";: INPUT LOC$ 

740 F I LEREC$=ACODE$ 

750 FILEREC$(4)=L0C$ 

800 REM PERFORM FILE UPDATING 

810 GOSUB 9600 

820 PRINT #CHANNELj F I LEREC$ 

830 GOSUB 9500 

840 GOTO 400 

900 REM ALLOW DELETES 

910 PRINT 

920 PRINT "(Y/N) DO YOU WISH TO DELETE ANY ";: INPUT YN$ 
930 IF YN$<>"Y" THEN 1200 
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1000 REM SPECIFY WHICH TO DELETE 
1010 PRINT 

1020 PRINT "(0=END) AREA CODE •»;: INPUT ACODE$:IF ACODE$="0" THEN 1200 

1100 REM SEARCH ACTIVE RECORDS FOR MATCHING AREA CODE 

1110 FOR RECORD=1 TO FILEMAX 

1115 GOSUB 9600 

1120 IF STS=1 THEN GOSUB 5100 

1125 NEXT RECORD 

1130 GOSUB 9500 

1140 GOTO 1000 

1200 REM PRINT FILE TO SCREEN 

1210 PRINT : PR I NT "CODE","LOCATION":PRI NT 

1220 FOR REC0RD=1 TO FILEMAX 

1230 GOSUB 9600 

1240 IF STS=1 THEN GOSUB 5200 

1250 NEXT RECORD 

1 300 REM ALLOW HARDCOPY 

1310 PRINT : PR I NT "(Y/N) DO YOU WANT A PRINTED LIST M ;: INPUT YN$ 

1320 IF YN$<>"Y" THEN 4900 

1330 LPRINT "CODE","LOCATION":LPRINT 

1340 FOR RECORD* 1 TO FILEMAX 

1350 GOSUB 9600 

1360 IF STS=1 THEN GOSUB 5300 

1370 NEXT RECORD 

1380 GOTO 4900 

4900 REM END 

4910 CLOSE #CHANNEL 

4920 PRINT "END OF EXECUTION" 

4930 END 

5000 REM PROCESS ACTIVE RECORD/DISPLAY 
5010 INPUT #CHANNEL,FILEREC$ 
5020 IF FILEREC$(1,3X>AC0DE$ THEN RETURN 
5030 MATCH =1 

5040 PRINT "LOCATION: ";F I LEREC$(4) 
5050 RETURN 

5100 REM PROCESS ACTIVE RECORD/DELETE 
5110 INPUT #CHANNEL,FILEREC$ 
5120 IF FILEREC$(1,3X>AC0DE$ THEN RETURN 
5130 GOSUB 9450 

5150 PRINT "DELETED ";F ILEREC$(4) 
5160 RETURN 

5200 REM PROCESS ACTIVE RECORD/PRINT 
5210 INPUT #CHANNEL,FILEREC$ 
5220 PRINT FILEREC$(1,3),FILEREC$(4) 
5230 RETURN 

5300 REM PROCESS ACTIVE RECORD/LPRI NT 
5310 INPUT #CHANNEL,FILEREC$ 
5320 LPRINT F I LEREC$( 1 ,3) ,F I LEREC$(4) 
5330 RETURN 
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9300 REM 'FILEOPEN.SUB' WBB 3-30-81 

9305 REM OPEN A FILE IN MODE 12 AND DEFINE ALL VARIABLES 

9310 OPEN #CHANNEL, 12,0, FILES 

9315 DIM FILEHED$(124) 

9320 INPUT #CHANNEL,F I LEHEDS 

9325 F I LESEC=ASC(F I LEHED$( 1 ) )*256+ASC(FI LEHEDS ( 2) ) 
9330 F I LEBYT=ASC(F I LEHEDS (3 ) ) 
9335 FILESTS=ASC(FILEHED$(4)) 

9340 FILEMAX=ASC(FILEHED$(5))*256+ASC(FILEHED$(6)) 
9345 F I LELEN=ASC(F I LEHEDS (7) ) *256+ASC( F I LEHEDS ( 8) ) 
9350 DIM F ILEPTR$(4+4*F I LEMAX) ,F ILERECS(F ILELEN) 
9355 INPUT #CHANNEL,F I LEPTRS 
9360 RETURN 

9400 REM 'FILEADD.SUB' WBB 3-30-81 

9405 REM ALLOCATE THE NEXT AVAILABLE RECORD 

9410 RECORD=0 

9415 IF F I LEMAX=0 THEN RETURN 

9420 FOR REC0RD1=1 TO F I LEMAX 

9425 B=RECORD 1*4+4 

9430 IF FILEPTRS(B,B)=CHRS(0) THEN 

RE CORD =RE CORD 1 : RE CORD 1 =F I LEMAX: F I LEPTRS (B,B)=CHR$( 1 ) 

9435 NEXT RECORD 1 

9440 RETURN 

9450 REM 'FILEDEL.SUB' WBB 3-30-81 

9455 REM DELETE AN ACTIVE RECORD 

9460 B=REC0RD*4+4 

9465 FILEPTRS(B,B)=CHRS(0) 

9470 RETURN 

9500 REM *F I LEPTR.SUB' WBB 3-19-81 
9510 REM WRITE F I LEPTRS 

9515 S=ASC(FILEPTR$(1))*256+ASC(FILEPTR$(2)) 
9520 B=ASC(FILEPTR$(3)) 
9525 POINT #1,S,B 
9530 PRINT #1;F I LEPTRS 
9535 RETURN 

9600 REM 'FILEPOS.SUB' WBB 3-31-81 
9605 REM POINT FILE TO RECORD 

9610 S=ASC(F I LEPTRS (REC0RD*4+1 ) )*256+ASC(F I LEPTRS (REC0RD*4+2) ) 
9615 B=ASC(F I LEPTRS ( REC0RD*4+3 ) ) 
9620 STS=ASC(FILEPTR$(REC0RD*4+4)) 
9625 POINT #CHANNEL,S,B 
9630 RETURN 



APPENDIX IX - INITIALIZATION 





POWER 



NO (MIDDLE 
OF COLDSTART) 




SEI 
WARMST=0 



006% 




YES 



GOTO STANDALONE 
DIAGNOSTIC 
CARTRIDGE 
(JMP ($BFFE) ) 



NO 



FIND # OF 4K BLOCKS 
OF RAM (TRAMSZ) 
INITIALIZE POKEY, ANTIC, 
CTIA/GTIA 



CLEAR O.S. RAM 
( $200-3FF , $1 0-7F ) 



m (RESET) NO 




YES(POWERUP) 



CLEAR ALL RAM 
($08-TRAMSZ) 
SET DEFAULT CARTRIDGE TO 
BLACKBOARD (DOSVEC=BLKBDV) 
SET COLDST TO MIDDLE OF POWER-UP 
, (COLDST=$FF) 




SET SCREEN 


MARGINS 


(LMARGN=2 


RMARGN; 


=39) 



i 



MOVE IRQ VECTOR TABLE 
FROM ROM TO RAM 
( VDSLST-V VBLKD ) 

\ 



c 
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) 
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I 



CLEAR BREAK KEY (BRKKEY=$FF) 
SET MEMORY SIZE 
RAMSIZ=TRAMSZ 
MEMTOP=TRAMSZ 
MEMLO=$700 



I 



INITIALIZE DEVICE HANDLERS 


EDITOR 


(BO 


SCREEN 


(SO 


KEYBOARD 


(KO 


PRINTER 


(PO 


CASSETTE 


(CO 



YES 


SET CASSETTE BOOT 


NSTART KEY^ 


(CKEY-1) 








NO CASSETTE BOOT 
(CKEY=0) 






L 







ENABLE IRQ INTERRUPTS 



MOVE DEVICE HANDLER 
TABLE FROM ROM TO RAM 
( TBLENT HATAB S ) 




YES 


INITIALIZE 






B CARTRIDGE 






(JSR(9FFE)) 



CLEAR B CART. 
FLAG (TSDAT=0 ) 



C 



E 



I 
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SET B CARTRIDGE 
FLAG (TSDAT=l) 



J 
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o 



01 



DO CASSETTE 
BOOT 



PRINT 'BOOT ERROR' 
ON SCREEN 



— 



I 



BOOT?=1 



YES 




B00T?=2 




YES 



INITIALIZE 
A CARTRIDGE 
(3SR($BFFE) ) 



CLEAR A CART. 
FLAG (TRAM5Z=0) 
( JSR($BFFE) ) 



£ 



SET A CART. 
FLAG(TRAMSZ=1) 



OPEN EDITOR 
(E:) 




XLS. 




POWER-UP 



3 



WAIT FOR VBLANK 
TO SET UP SCREEN 



YES (RESET) 




\ 



YES 



RUN PROGRAM 
BOOTED 
(XSK(CASINI)) 



c 
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PRINT 
•BOOTERROR' 



GOTO A 
CARTRIDGE 

(JMP($BFFA^) 



GOTO B 
CARTRIDGE 
( JMP($9FFA) ) 



YES 



YES 



YES 






[ NO 










CLEAR POWER-UP 


FLAG (COLDST=0) 







RUN 

CARTRIDGI 
? 



NO 



RUN 

CARTRIDGI 

? 




NO 


GOTO DOS OR 






CASSETTE PROGRAM OR 






BLACKBOARD 
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APPENDIX X 
GTIA 



The GTIA is a new display chip that will someday replace CTIA. Actually 
It Is nothing more than a CTIA with a few more features. It simply provides 
three additional modes of Interpretation of Information coming from the ANTIC 
chip. ANTIC does not require a new mode to talk to GTIA; Instead, It uses 
the high resolution mode $F. GTIA is completely upward compatable with the 
CTIA. A brief summary of CTIA f s features follows so that the differences 
between CTIA and GTIA can be presented. 

The CTIA Is designed to display data on the television screen. It 
displays the playfleld, players and missiles, and detects any overlaps or 
collisions between objects on the screen. CTIA will Interpret the data 
supplied by ANTIC according to six text modes and eight graphics modes. In a 
static display, It will use the data from ANTIC to display hue and luminance 
as defined In one of four color registers. The GTIA expands this to use all 
nine color registers or 16 hues with one luminance or 16 luminances of one 
hue In a static display. 

The three graphics modes of GTIA are simply three new Interpretations of 
ANTIC mode $F, a hl-resol utlon mode. All three modes affect the playfleld 
only. Players and missiles can still be added to Introduce new hues or 
luminances or to use the same colors and luminances In more than one way. 
All displays of hues and luminances can still be changed on-the-fly with 
display list Interrupts. The GTIA uses four bits of data from ANTIC for each 
pixel, called the pixel data. Each pixel Is two color clocks wide and one 
scan line high. Thus, the pixels are roughly four times wider than their 
height. The display has a resolution of 80 pixels across by I92 down. Each 
line then requires 320 bits or 40 bytes of memory, the same number of bytes 
used In ANTIC mode $F. Therefore for a program to run the GTIA modes It must 
have at least 8K of free RAM for the display. 

The GTIA modes are selected by the priority register, PRIOR. PRIOR Is 
shadowed at location $26F hex by the OS and Is located at D01B hex In the 
chip. Bits D6 and D7 are the controlling bits. When neither Is set there 
are no GTIA modes and GTIA operates just like CTIA. When D7 Is 0 and D6 Is 
1, Mode 9 Is specified which allows 16 different luminances of the same hue. 
Remember the pixel data supplied by ANTIC Is four bits wide which means 16 
different values can be represented. Players and missiles can be used In 
this mode to Introduce additional hues. When D7 Is 1 and D6 Is 0, Mode 10 Is 
specified. This mode gives nine colors In the display by using the four 
playfleld color registers plus the four pi ayer/mlss I le color registers plus 
the one background color register. When players are used In this mode, the 
four p layer/miss I le color registers are used for them also. When D7 Is 1 and 
D6 Is 1, Mode 11 Is specified. This mode gives 16 hues with the same 
luminance again because 16 different values can be represented by four bits. 
Players and missiles can be used In this mode to Introduce different 
luminances. 



GTIA 



PRIOR 











! 1 1 


1 



D7 


D6 


0 
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0 


1 


1 


0 


1 


1 



OPTION 



No GTIA modes 

(CTIA operation) 

1 Hue, 16 Luminances 

9 Hues/Luminances 

16 Hues, 1 Luminances 



(Modes 0-8) 

(Mode 9) 
(Mode 10) 
(Mode 11) 



Figure X.1 
Bit Pattern In PRIOR selects GTIA 



Setting up the new GTIA modes Is as simple as setting up the present 
modes used In CTIA. To Implement the modes from BASIC simply use the 
commands GRAPHICS 9, GRAPHICS 10, and GRAPHICS 11 for Mode 9, Mode 10, and 
Mode 11 respectively. In Assembly Language selecting one of these modes Is 
Identical to opening the screen for any of the other modes. If you are 
building your own display list then PRIOR must be set to select the correct 
mode as In Figure X.1. 

Mode 9 produces up to 16 different luminances of the same hue. ANTIC 
provides the pixel data which selects one of 16 different luminances. The 
background color register provides the hue. In BASIC this Is done using the 
SETC0L0R command to set the hue value In the upper nybble of the background 
color register, and to set the luminance value In the lower nybble to all 
zeroes. The format of the command Is 



SETCOLOR 4, hue value,0 



where 4 specifies the background color register, "hue value" sets the hue and 
can be anything from 0 to 15, and 0 will set the luminance part of the 
register to zero. This has to be done because the pixel data from ANTIC will 
then be logically 0R f ed with the lower nybble of the background color 
register to set the luminance that appears on the screen. The COLOR command 
Is then used to select luminances for drawing on the screen by using values 
from 0 to 15 as Its parameter. So a BASIC program will Include at least the 
following statements to use Mode 9: 



GRAPHICS 9 
SETCOLOR 4,12,0 

FOR l= 0 TO 15 
COLOR I 



to specify Mode 9 

to Initialize the background color 

register to some hue, In this case green 

some method where the 

COLOR command Is used 
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PLOT 4,1+10 to vary luminance. 

NEXT I 

In Assembly Language use the OS shadow for the background color register S2C8 
to set the hue In the upper four bits with hex values from $0 to $F. If CIO 
calls are used, store the pixel data Into the OS register ATACHR located at 
$2FB. This selects the luminance with hex values from $0 to $F. If you are 
maintaining your own display data then the pixel data goes directly Into the 
left or right half of the display RAM byte. 
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one constant hue 
set by background 
color register 



LUMINANCE 
16 luminances 
selected by 
pixel data 



OR 1 ED TOGETHER TO GIVE 
FINAL COLOR ON DISPLAY 



Figure X.2 

Background Color Register 0R ! ed with pixel data to give final color. 



Mode 11 Is similar to Mode 9 except that It provides 16 different hues 
all with the same luminance. Again ANTIC will provide the pixel data to 
select one of 16 different hues. In BASIC the SETCOLOR command Is used to 
set up the single luminance value In the lower nybble of the background color 
register, and In the upper nybble, the hue value will be set to all zeroes. 
The format of the command Is 

SETCOLOR 4,0, luminance value 

where 4 specifies the background color register, 0 sets the upper nybble to 
zero and "luminance value" sets the value of the luminance and can range from 
0 to 15. As with the other graphics modes (except Mode 9), the first bit of 
the luminance Is not used, so effectively only even numbers result In 
distinct luminances which gives eight different possible luminances In this 
mode. The COLOR command Is used In this mode to select the various hues by 
using values from 0 to 15 In Its parameter. The pixel data from ANTIC will 
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be logically OR'ed with the upper nybble of the background color register to 
set the hue part of the value that ultimately generates the color on the 
screen. So a BASIC program using Mode 11 will Include at least the following 
statements : 



GRAPHICS 11 
SETCOLOR 4,0,12 



FOR l= 0 TO 15 
COLOR I 
PLOT 4,1+10 
NEXT I 



to specify Mode 1 1 

to Initialize the background 

color register to some luminance, 

In this case very bright 

some method where the 

COLOR command Is used 

to vary the hue 



In Assembly Language use the OS shadow for the background color register 
$2C8 to set the luminance In the lower four bits with hex values from $0 to 
$F. If CIO calls are used, store the pixel data Into ATACHR located at $2FB. 
This selects the hue with hex values from $0 to $F. If you are maintaining 
your own display data then the pixel data goes directly Into the left or 
right half of the display RAM byte. 
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Figure X.3 

Background Color Register 0R f ed with pixel data to give final color. 



Mode 10 will allow all nine color registers to be used In the playfleld 
at one time. Each color register to be used must be set to some combination 
of hue and luminance. The pixel data from ANTIC is used in this mode to 
select one of the color registers for display. In BASIC the SETCOLOR command 
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can be used as described In the BASIC Reference Manual to set the colors In 
the background and the four playfleld registers. These can also be set by 
using the POKE Instruction to addresses 708-712 where the four playfleld 
registers and the background register are located. The POKE Instruction must 
be used to set the four player/mlssl le color registers at locations 704-707. 
The COLOR command Is used to select the color register desired. The only 
meaningful values for Its arguement are 0 to 8. A problem arises with this 
mode. ANTIC supplies four bits of data per pixel, as It does with Modes 9 
and 11. This allows for the selection of 16 color registers. However, only 
nine color registers exist In the hardware. An Illegal data value between 9 
and 15 will select one of the lower value color registers. A BASIC program 
using mode 10 will Include: 

1) a GRAPHICS 10 command to specify Mode 10; 

2) a set of POKE Instructions to put hues and luminances Into the 
color registers, 

OR a combination of SETC0L0R commands and POKE Instructions to do 
that; 

3) a COLOR command to select the desired color register. 

In Assembly Language, store the pixel data In ATACHR ($2FB) or directly Into 
the display RAM byte as In Modes 9 and 11. In this mode the pixel data can 
range from 0 to 8 and selects one of the nine color registers. 



COLOR STATEMENT COLOR REGISTER OS SHADOW 

VALUE USED 

0 DO 12 2C0 

1 DO 13 2C1 

2 DO 14 2C2 

3 D015 2C3 

4 D016 2C4 

5 DO 17 2C5 

6 DO 18 2C6 

7 DO 19 2C7 

8 D01A 2C8 



Figure X.4 

Color Register numbers and locations and COLOR command reference 




An Important question arises In conjuctlon with GTIA concerning 
compatabl I Ity . GTIA Is fully upward compatible with the CTIA and all 
software that runs on a CTIA system will run the same way on a system with 
GTIA. This means you still have the full use of players and missiles, still 
have collision and overlap detection and display list interrupts. The GTIA 
graphics modes are fully supported by the OS and all graphics commands and 
utilities that run In the CTIA modes can be used In GTIA modes. 
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More colors are available to display at one time on the screen. Sixteen 
color changes can occur on one line totally Independent of processor 
Intervention. This Is actually better than what could be done with display 
list Interrupts which could give at most only 12 color changes per line. 
Much finer contour and depth can be represented using the shading available 
In Mode 9. This means three dimensional graphics can be realistically 
displayed. 

On the other hand, there are some disadvantages. GTIA modes are map 
modes, there can be no text displayed In these modes. A custom display list 
must be used to switch to a mode that supports character displays. The GTIA 
pixel Is a long, skinny horizontal rectangle (4:1, width to height) and does 
not represent curved lines well. Because each pixel uses four bits of 
Information, GTIA requires nearly 8K of free RAM to operate. Although It Is 
upward compatable, It Is NOT downward compatable. Thus programs which use 
GTIA modes will NOT produce correct displays on computers that have CTIA f s. 
They may well be recognizable but will not be as colorful. There Is no way 
currently for a program to determine whether or not a GTIA Is present In a 
system. 



X-6 



GLOSSARY 



$ 

The symbol which Indicates a number should be Interpreted as hexadecimal. 



ANTIC 

This Is a separate microprocessor contained within the ATARI 400/800 
which Is dedicated to the television display. ANTIC Is user-programmable 
with an Instruction set, a program (the "display list"), and data (the 
"display memory") . 



ATTRACT MODE 

This Is a feature provided by the operating system which, after nine 
minutes without a key being pressed, cycles the colors on the screen through 
random hues at lowered luminances. This Insures that a computer left 
unattended for several hours doesn't burn a static Image Into the television 
screen . 



BACKGROUND 

The area of the television screen display upon which playei — missile 
graphics objects or playfleld objects and/or text are projected. Background 
has Its own user-definable color. 



BORDER 

In BASIC Mode 0, this Is the area of the television screen display which 
Is formed by the four edges of the screen. The border takes background color. 



BRKKEY 

A flag set when the OS senses that the BREAK key Is typed. BRKKEY f s 
normal value Is $FF — If It changes, then the BREAK key has been typed. 



BYTE COUNT 

This Is the file pointer's position within a sector on diskette. 



CASSETTE BOOT FILE 

A standard or usei — created file which boots from cassette at powei — up or 
SYSTEM RESET. 
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CHARACTER GRAPHICS 

The technique of redefining the Individual characters of a character set 
to form graphics Images Instead of text characters. 



CHARACTER IMAGE 

The unique 8X8 pixel grid which defines a particular character's shape. 
CHARACTER MODE 

This Is a specific type of ANTIC display mode which displays screen 
display memory data bytes as characters, using a character set. There are 6 
ANTIC character modes, 3 of which are accessible from BASIC. 



CHARACTER NAME BYTE 

A one-byte ANTIC display memory value which selects a unique character 
within the current character set by the character's numerical position In 
that set. 



CHARACTER SET INDIRECTION 

The technique of specifying to ANTIC a particular character set to be 
used by placing that set's beginning page address Into CHBAS. 



CHBAS 

The OS shadow location which ANTIC uses to find the current character 
set which is to be used for character display modes. CHBAS Is at decimal 
address 756. 



CHECKSUM 

This Is a single byte sum of all the bytes In a record (either disk I/O 
or cassette I/O). For cassette I/O this Includes addition of the two marker 
characters, computed with end-around carry. 



CIO 

Acronym for Central I/O system routine. CIO routes I/O control data to 
the correct device handler and then passes control to the handler. CIO Is 
also the common entry point for most of the OS I/O functions. 



G-2 



GLOSSARY 



COARSE SCROLLING 

The process of altering the display list LMS (Load Memory Scan) address 
bytes In order to vertically or horizontally scroll the screen Image, one 
byte at a time. This Is accomplished by adding 1 to or subtracting 1 from 
the LMS address bytes. 



COLDSTART 

Synonym for the power-up process which performs a series of system 
database Initializations when the computer power switch Is turned on. After 
coldstart, the system surrenders control to the user. 



COLLISION 

This occurs when a player Image In player-miss! le graphics coincides 
with another Image. There are 60 possible collisions and each one has a bit 
assigned to It that can be checked. These bits are mapped Into 16 registers 
In CTIA (with only the lower 4 bits used). 



COLLISION DETECTION 

Primarily of value for games. This Is a hardware- Implemented ability to 

detect If any one of the 60 p I ayer-ml ss 1 1 e collision possibilities has 
occurred. 



COLOR 

One of 128 values obtained from a hue-lumlnos Ity combination which Is 
stored In a color register. 



COLOR CLOCK 

The standard unit of horizontal distance on the television screen. 
There are 228 color clocks In a horizontal scan line. 



COLOR REGISTER 

A hardware register (with corresponding OS shadow location) used to add 
color to various portions of the screen display. There are 9 color registers 
available on the ATARI Personal Computer System. 



COLOR REGISTER INDIRECTION 

The technique of specifying a particular color by coding Its value Into 
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a color register. 



COLOR SIGNAL 

This contains the color Information which Is combined with the primary 
signal to form the modulating television signal. The Color Signal oscillates 
at 3.579 MHZ. 



COLRSH 

A zero-page location ($4F) set up and updated by the OS during vertical 
blank Interrupts for ATTRACT mode processing. When ATTRACT mode Is In force, 
COLRSH Is given a new random value every four seconds. 



COMMAND 

In BASIC, this Is the first executable token of a BASIC statement that 
tells BASIC to Interpret the tokens that follow In a particular way. 



CONSTANT 

In BASIC, this Is a six-byte BCD value preceeded by a special token. 
This value remains unchanged throughout the program execution. 



CONTROL BYTE 

In cassette I/O, this Is part of every record. It contains one of three 
possible values. 



CTIA 

A television Interface chip which Is controlled primarily by ANTIC. 
CTIA converts ANTIC f s digital commands Into a signal that Is sent to the 
television. 



CURRENT STATEMENT 

In BASIC, this Is the current token within a line of the Statement Table c 



CYCLE STEALING 

This occurs when ANTIC Interrupts 6502 processing In order to perform 
DMA functions for screen display purposes. 
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CYCLIC ANIMATION 

The technique of repetitively flipping through colors, graphics Images, 
or character graphics sets to animate screen Images. 

DCB 

Acronym for Device Control Block. The DCB Is used by the I/O subsystem 
to communicate between the device handlers and SIO. 



DEVICE HANDLERS 

Routines present In OS ROM which are called through CIO (as long as the 
handler has an entry In HATABS) to communicate to particular devices. 
Currently supported are the Display Editor, the Screen, the Keyboard, the 
Printer, and the Cassette. 



DEVICE SPEC 

A special HATABS code which specifies a particular I/O device. 



DIAGONAL SCROLLING 

This results from the combination of horizontal and vertical scrolling 
of the screen Image. 

DISPLAY FORMAT 

A screen Image on paper which Is translated Into a sequence of mode 

lines which themselves eventually get translated Into ANT I C 1 s display list 
Instructions. 



DISPLAY LIST 

ANTIC's "program 11 defined by the user or provided automatically (through 
a GRAPHICS command) by BASIC. The display list specifies where the screen 
data may be found, what display modes to use to Interpret screen data, and 
what special display options (If any) should be Implemented. 



DISPLAY LIST INTERRUPT 

A special ANTIC display list Instruction which Interrupts the 6502 
microprocessor during the drawing of the screen Image, allowing the 6502 to 
change the screen parameters. 
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DISPLAY MODE 

Either a BASIC or ANTIC methodology for Interpreting text or map data 
bytes In screen memory and displaying them on the screen. 



DLI VECTOR 

This Is a two-byte pointer (lo byte, high byte) to the Display List 
Interrupt service routine. This vector Is set by the user and Is located at 
[512,513] decimal. 



DMA 

Direct Memory Access. This occurs when ANTIC or the 6502 fetch an 
Instruction byte or data byte from memory. 



DMACTL 

The hardware register whose bit settings control, among other things, 
player vertical resolution and player-mlsst le graphics enabling. 

DOS 

Acronym for Disk Operating System which Is an extension of the OS that 
allows the user to access disk drive mass storage as flies. 



DOUBLE-LINE RESOLUTION 

A unit of vertical resolution for a player In playei — missile graphics. 
Each player byte occupies two horizontal scan lines on the screen, and each 
player table Is 128 bytes long. 

DRKMSK 

A zero-page ($4E) location set up and updated by the OS during vertical 
blank Interrupts for ATTRACT mode processing. Usage of DRKMSK lops off the 
highest luminance bit of the right nybble of a color register's value. This 
Insures a low luminance for ATTRACT mode. 



DUP 

Acronym for Disk Utility Package. DUP Is a set of utilities for 
diskette, familiarly seen as the DOS menu. DUP executes commands by calling 
FMS through CIO. 
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DYNAMIC DISPLAY LIST 

This Is an ANTIC display list which the 6502 changes during vertical 
blank periods, allowing for even a greater degree of flexibility In the 
screen display. 



EOL 

In BASIC, "End-of-Llne", a character with the value $9B. 



FILE 

In cassette I/O, this consists of a 20-second leader of the mark tone 
plus any number of data bytes, and end-of-flle. In diskette I/O this 
consists of a number of sectors linked by pointers (125 data bytes per 
sector) . 



FILE POINTER 

For diskette I/O, this Is a value which Indicates the current position 
In a file by specifying the Sector Number and the Byte Count, DOS keeps a 
file pointer for every file currently open. 



FINE SCROLLING 

The process of horizontally or vertically scrolling a screen Image In 
color clock or scan line increments. The horizontal scrolling and vertical 
scrolling hardware registers must be used to fine scroll. 



FMS 

File Manager System. FMS Is a non-resident device handler which 
supports some special CIO functions. 



FONT 

A collection of characters which constitutes a character set. These 
characters can be either text or graphics Images. 



FOREGROUND 

Equivalent to playfleld, the area of the screen which directly overlays 

the background of the screen. Foreground Is formed by map displays and/or 
text. 
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FORMAT 

A resident disk handler command that clears all the tracks on diskette, 
FUNCTION 

In BASIC, a token that when executed returns a value to the program. 

GRAPHICS INDIRECTION 

A special feature of the ATARI system which allows color register and 
character set generality by using Indirect pointers to color and character 
set values. 

HATABS 

The device handler entry point table which is used by CIO. HATABS Is 
located at $031 A. 

HORIZONTAL BLANK 

This Is the period during which the electron beam (as It draws the 
screen Image) returns from the right edge of the screen to the left edge. 

HORIZONTAL POSITION REGISTER 

A specialized register which contains a user-definable value for the 
horizontal position of a player in p layer-miss I le graphics. This value Is In 
units of color clocks. 

HORIZONTAL SCAN LINE 

The fundamental unit of measurement of vertical distance on the screen. 
The scan line Is formed by a single trace of the electron beam across the 
screen. 

HORIZONTAL SCROLL ENABLE BIT 

This Is bit D6 of the ANTIC display Instruction which enables horizontal 
scrolling through the HSCROL register. 

HORIZONTAL SCROLLING 

This Is the process of "sliding" the screen "window" to the left or 
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right over display memory In order to display more Information than could be 
seen with a static screen. Either coarse or fine horizontal scrolling Is 
aval I able. 



HSCROL 

This Is the horizontal fine scrolling register located at $D404, 
containing the number of clocks by which a line Is to be horizontally 
scro I I ed . 



HUE 

The upper nybble value of a color register's color. There are 16 
possible hues ($0 to $F) which In combination with a luminosity value 
constitute distinct "colors." Examples of hues are "black", "red", and 
"gold." 



I/O SUBSYSTEM 

A set of system routines that Interface to the I/O hardware. 



I/O SYSTEM CONTROL BLOCKS 

These blocks are elements of the I/O subsystem which are used to 
communicate Information about the I/O function to be executed. 



IMMEDIATE MODE 

In BASIC, the mode where the Input line Is not proceeded by a line 
number. BASIC Immediately executes the line. 



INPUT BAUD RATE 

For cassette I/O, this Is assumed to be a nominal 600 baud (physical 

bits per second). However, this rate Is adjusted by SIO to account for drive 

motor variations, stretched tape, etc. 

INPUT LINE BUFFER 

In BASIC, from $580 to $5FF. 



INTER-RECORD GAP 



For cassette I/O records, this consists of the Post-record gap of a 
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given record followed by the Pre-record Write Tone of the next record. 



INTERIM MASTER 

In the mass production of cassette tapes, this Is the backup copy for 
the Work Master tape. 



IOCB 

Acronym for Input/Output Control Block. There are eight of these whose 
function Is to communicate between the user programs and CIO. 



IRQ 

Maskable (can be enabled or disabled by the 6502) Interrupts such as the 
Break Key IRQ. 



IRQEN 

The write-only register that contains the IRQ enable/disable bits. 
IRQEN Is shadowed at POKMSK. 



KERNEL 

A primitive software/hardware technique which consists of a 6502 program 
loop which Is precisely timed to the display cycle of the television set. 
The kernel code monitors the VCOUNT register and consults a table of screen 
changes catalogued as a function of VCOUNT values so that the 6502 can 
arbitrarily control all graphics values for the entire screen. 



LINE 

In BASIC, a line consists of one or more BASIC statements preceeded 
either by a line number In the range of 0 to 32767, or an Immediate mode line 
with no line number. 



LOMEM 

In BASIC, this Is the pointer (£80,811] decimal) to a buffer used to 
tokenlze one line of code. The buffer Is 256 bytes long, residing at the end 
of the operating system's allocated RAM. 



LUMINANCE 
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The lower nybble of a color register's color. There are 8 even-numbered 
values for luminance ($0 to $F, even values only) which In combination with 
hue values produce the 128 "colors" available on the ATARI 400/800. 



MAP MODE 

This Is a specific type of ANTIC display mode using simple colored 
screen pixels Instead of characters for the screen display. There are 8 
ANTIC map modes, with varying degrees of resolution. Six of these are 
cal I able from BASIC. 



MARK 

For cassette I/O, this Is a 5327 HZ frequency. 



MARKER CHARACTER 

For cassette I/O, this Is a 55 (hex) value whose purpose Is for 
adjusting the baud rate. Including the start and stop bits, each marker 
character Is 10 bits long. 



MASTER TAPE 

In cassette tape mass production, this Is an open-reel, 1/4 track, 1/4 

Inch tape recorded at 7 1/2 Inches per second. The Master Tape becomes the 

Source Master prior to the duplication process. 



MEMT0P 

In BASIC, a pointer ([90,91] decimal) to the top of application RAM, the 
end of the user program. Program expansion can occur from this point to the 
end of free RAM, which Is defined by the start of the display list. This 
MEMT0P Is not the same as the OS variable called MEMT0P. 



MISSILE 

A one-dimensional Image In RAM used In p I ayer-ml ss 1 1 e graphics which is 
2 bits wide. There Is a maximum of 4 missiles, one for each player. 



MISSILE COLOR 

The color of a missile In p I ayer-mlss 1 1 e graphics. Each of the four 
missiles takes on the color of Its associated player. 
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MODE LINE 

A collection of horizontal scan lines for screen displays. Depending 
upon the BASIC or ANTIC display mode In effect, a mode line will be composed 
of varying numbers of scan lines. By the same token, depending upon the 
display mode, a screen Image will be composed of varying numbers of mode 
I I nes • 



MON I TOR 

A program In ROM that handles both the system power-up and SYSTEM RESET 
sequences. 



N-BIT 

A 6502 processor status register bit which Is set by, among other 
things, I/O calls to Indicate the sucess or failure of an I/O operation. 



NARROW PL A YF I ELD 

A screen display width option equal to a width of 128 color clocks. 



NMI 

Non-Maskable Interrupt (I.e., cannot be disabled by the 6502). The 
Display List Interrupt and the Vertical Blank Interrupt are both NMIs. These 
can be disabled with the ANTIC NMI EN register. 



NMI EN 

The Non-Maskable Interrupt Enable relster which controls enabling of 
various Interrupts such as the Display List Interrupt (DLI). 



NORMAL IRG MODE 

In cassette I/O, this Is a mode where the tape always comes to a stop 
after each record Is read. If the computer stops the tape and gets Its 
processing done fast enough, then the next read may occur so quickly that the 
cassette deck may see only a slight dip In the control line. 



NORMAL PLAYF I ELD 

A screen display width option equal to a width of 160 color clocks. 
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OPERATOR 

In BASIC, any one of the 46 tokens that In some way move or modify the 
values that follow them. 



OPERATOR STACK 

In BASIC, a software stack where operators are placed when an arithmetic 
BASIC expression Is being evaluated. 



OVERSCAN 

The "spreading out" of a television Image by the raster scan method of 
display so that the edges of the picture are off the edge of the television 
tube. This guarantees no unsightly borders In the television picture. 

PIXEL 

The standard point-unit of vertical distance on the television screen. 
The normal limit of a television set used with the ATARI 400/800 Is 192 
pixels vertical ly . 



PLAYER 

A one-dimensional RAM Image used In playei — missile graphics which can be 
128 bytes (double- line resolution) or 256 bytes (single- line resolution) 
long. The player appears as a vertical band 8 pixels wide stretching from 
the top of the screen to the bottom. There Is a maximum of four Independent 
players. 



PLAYER COLOR 

The color of a player In player-mlssl le graphics. Each of the four 
Independent players has Its own color stored In Its associated color register. 



PLAYER-MISSILE AREA 

A RAM area which contains the Images of the four players and four 
missiles of player-mlssl le graphics, as well as some extra RAM. The 
playei — missile area must be on a 1K boundary for single-line resolution 
players or a 2K boundary for double- line resolution players. 



PLAYER-MISSILE GRAPHICS 

Atari f s solution for simplifying animation by creating an Image (a 
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f player f or f mlssile f ) which Is one-d Imens Iona I In RAM but two-dimensional on 
the screen. 



PLAYF I ELD 

The area of the screen which directly overlays the background of the 
screen. Map graphics and/or text form this playfleld. 

PLAYF I ELD ANIMATION 

The technique of animating an object by moving Its two-dimensional Image 
bytes to new locations In screen memory, and then erasing the defining bytes 
of the old Image before displaying the newly-moved Image. 



PMBAS 

A register which points to the beginning of the player-miss I le area. 



POKEY 

A digital I/O chip which handles the serial I/O bus, audio generation, 
keyboard scan, and random number generation. POKEY also digitizes the 
resistive paddle Inputs and controls maskable Interrupt (IRQ) requests. 



POKEY TIMERS 

Unlike System Timers, the POKEY chip timers are clocked by frequencies 
set by the user. 



POST-RECORD GAP 

A pure mark tone frequency used as a post-record delimiter In cassette 

I/O. 



PRE-RECORD WRITE TONE 

A pure mark tone frequency used as a pre-record delimiter In cassette 

I/O. 



PRIMARY SIGNAL 

This contains the luminance Information — brightness data, horizontal 
and vertical syncs and blanks — of the modulated television signal. 
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PR I OR I TY-CONTROL REG I STER 

Also known as PRIOR, and shadowed at GPRIOR. This register specifies 
which playfleld, player, or background Images have priority In the case of 
image overlaps during the screen display process. 



RAM VECTOR 

Alterable system vector that contains two-byte addresses to system 
routines, handler entry pointers, or to Initialization routines. RAM vectors 
are Initialized at power-up and SYSTEM RESET. 



RASTER SCAN 

A television display system which uses an electron beam generated at the 
rear of the television tube. The beam sweeps across the screen In a regular 
left-to-right, top-to-bottom fashion. 



RECORD 

For diskette I/O, a group of bytes delimited by EOLs ($9B). For 
cassette I/O, this Is a group of 132 bytes which is composed of 2 marker 
characters for cassette speed measurement, a control byte, 128 data bytes, 
and the checksum byte. 



REDEFINED CHARACTER SET 

Any user-defined character set designated for use by ANTIC other than 
the standard character set In ROM. CHBAS (decimal address 756) contains the 
beginning page address of any redefined character set. 

RESIDENT DISK HANDLER 

This software performs five Important low- 1 eve I disk I/O functions such 
as FORMAT, READ SECTOR, WRITE SECTOR, WRITE/VERIFY SECTOR, and STATUS. 



ROM VECTOR 

Unalterable system vector that contains JMP Instructions to system 
routines. 



RTCLOK 

One of the system timers which Is 3 bytes In length and Is updated 
during immediate VBLANK. RTCLOK can be used as an application^ timepiece. 
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RUNSTK 

In BASIC, a pointer (C8E,8FD decimal) to the Run Time Stack. 



RUN TIME STACK 

In BASIC, a software stack which contains GOSUB and FOR/NEXT return 
address entries. 



SCREEN MEMORY 

A RAM area used by the 6502 to store bytes of data that will be fetched 
(by DMA) by ANTIC to be Interpreted and eventually displayed as Images on the 
screen . 



SECTOR 

On a diskette, this Is a 128-byte physical area. The diskette contains 
40 tracks with 18 sectors per track. 



SECTOR NUMBER 

A value from 1 to 719 which designates to which diskette sector the file 
pointer Is currently pointing. 



SETVBV 

A system routine which, among other functions, correctly sets the system 
timers and sets user-definable Interrupt vector addresses. 



SHADOW I NG 

The process whereby a software location Is used by the OS to update 
hardware registers during vertical blank periods. 



SHORT IRG MODE 

In cassette I/O, this means the tape Is not stopped between records. 
The BASIC commands "CSAVE" and "CLOAD" both specify this mode. 



SINGLE-LINE RESOLUTION 
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A unit of vertical resolution for a player In player-mlssl le graphics. 
Each player byte occupies one horizontal scan line on the screen, and each 
player table Is 256 bytes long. 

SIO 

Serial I/O system routine which handles communication between the serial 
device handlers In the computer and the serial bus. 



SIO INTERRUPTS 

These are 3 IRQ interrupts used by SIO to send and receive serial bus 
communications to serial bus devices. These 3 are VSERIR (Serial Input 
Ready), VSEROR (Serial Output Needed), and VSEROC (Transmission Finished). 



SOUND REGISTER 

Audio-producing hardware In the ATARI Personal Computer System which 
contains frequency, volume, and distortion Information, but not duration. 



SOURCE MASTER 

In the mass production of cassette tapes, this Is Identical to the 
Master Tape. 



SPACE 

For cassette I/O, this Is a 3995 HZ frequency output to the cassette 
tape as a delimiter In conjunction with mark tones. 



STANDARD CHARACTER SET 

The default character set resident In ROM which Is used by the ATARI 
400/800. 



STARP 

In BASIC, the pointer ([8C,8DD decimal) to the String Array Area. 
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STATEMENT 

In BASIC, this Is a complete "sentence" of tokens that causes BASIC to 
perform some meaningful task. In LIST form, statements are separated by 
colons. 



STATEMENT TABLE 

In BASIC, this Is a block of data which Includes all the lines of code 
that have been entered by the user and token I zed by BASIC. This table also 
Includes the Immediate mode line. 



STMCUR 

In BASIC, the pointer ([8A,8B] decimal) to the current BASIC statement. 



STMTAB 

In BASIC, this Is the pointer ([88,89] decimal) to the Statement Table. 



STRING ARRAY AREA 

In BASIC, this block contains all the string and array data. 



SYNC MARK 

This Is a 3995 HZ Space frequency used as a sort of "en d-of -record" 
marker for audio tracks on the cassette. In applications software It Is 
useful for synchronizing the computer screen display with cassette audio. 



SYSTEM DATABASE 

This Is an area which occupies RAM Pages 0 through 4, containing many 
locations that store Information of Interest to the user. 



SYSTEM TIMER 

A timer provided by the ATARI 400/800 that runs at the frequency of the 
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television frame which for North American T.V.s (NTSC) Is 59.923334 HZ. 
European (PAL) televisions run at 50 HZ. There are 6 system timers, and they 
are clocked as part of the vertical blank process. 



TELEVISION ARTIFACT 

This refers to a spot or "pixel" on the screen that displays a different 
color than the one assigned to It. "Art Ifactlng" Is possible In ANTIC modes 
2, 3, and 15 which correspond to BASIC modes 0, no mode, and 8. 



TEXT WINDOW 

On a screen display, this Is a two-dimensional area set aside for 
textual I/O with the user. 



TOKEN 

In BASIC, an 8-bit byte containing a particular execution code. 



TOKEN I Z I NG 

In BASIC, this Is the process of getting a line of Input and creating a 
series of 8-bit bytes which contain tokens, meaningful execution codes. 



VARIABLE 

In BASIC, a token that Is an Indirect pointer to Its actual value. 



VARIABLE NAME TABLE 

In BASIC, this Is the table containing a list of all the variable names 
that have been entered In a program. 



VARIABLE VALUE TABLE 

In BASIC, this table contains current Information on each variable. 
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VBREAK 

This Is the 6502 BRK Instruction IRQ vector. Whenever a $00 opcode (the 
software break Instruction) Is executed, this Interrupt occurs. VBREAK 
normally points to an RTI Instruction. 



VCOUNT REGISTER 

The ANTIC register which keeps track of which horizontal scan line ANTIC 
Is displaying. 



VDSLST 

This Is the Display List Interrupt NMI vector located at C$0200, $0201]. 



VERTICAL BLANK 

The period during which the electron beam (as It draws the screen Image) 
returns from the bottom of the screen to the top. This period Is about 1400 
microseconds In duration. 



VERTICAL BLANK INTERRUPT 

A non-maskable Interrupt which occurs every 60th of a second during the 
vertical blank time of the television display. During this Interrupt, the OS 
performs various housekeeping functions such as shadowing color registers. 



VERTICAL SCROLL ENABLE BIT 

This Is bit D5 of the ANTIC display list Instruction byte which enables 
vertical fine scrolling through VSCROL ($D405), the vertical fine scroll 
reg I ster . 



VERTICAL SCROLLING 

The process of vertically "rolling" the display screen "window" over a 
larger amount of screen data In display memory than can be displayed by a 
static screen window. Either coarse or fine vertical scrolling Is available 
on the ATARI 400/800. 
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VIMIRQ 

This Is the Immediate IRQ vector. All IRQs vector through this 
location. VIMIRQ normally points to the IRQ handler. This vector can be 
f stolen f to do user IRQ Interrupt processing. 



V I NTER 

This Is the Peripheral Interrupt IRQ vector. The Interrupt line Is also 
available on the serial bus. VINTER normally points to an RTI Instruction. 



VKEYBD 

This Is the keyboard IRQ vector which Is activated by pressing any key 
except BREAK. This vector normally points to the OS f s own keyboard IRQ 
routine. 



VNTD 

In BASIC, this Is the pointer ([84,85] decimal) to the Variable Name 
Table Dummy end. BASIC uses this pointer to Indicate the end of the name 
table. This pointer normally points to a dummy zero byte when there are less 
than 128 variables. When 128 variables are present, this points to the last 
byte of the last variable name. 



VNTP 

In BASIC, the pointer ([82,83] decimal) to the Variable Name Table. 



VPRCED 

This Is the Peripheral Proceed IRQ vector. The proceed line Is 

available to peripherals on the serial bus. This IRQ Is unused at the 

present and normally points to an RTI Instruction. 
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This Is the vertical fine scroll register located at $D405. Into VSCROL 
the user stuffs the number of scan lines by which the screen line Is to be 
vertically scrolled. 



VSER I N 

This Is the POKEY serial Input Ready IRQ vector. 



VSEROR 

This Is the POKEY serial Output Ready IRQ vector. 



VTIMR1 

This Is the POKEY timer 1 IRQ vector 



VTIMR2 

This Is the POKEY timer 2 IRQ vector 



VTIMR4 

This Is the POKEY timer 4 IRQ vector. 



VVBLKD 

This Is the Vertical Blank Deferred NMI Interrupt vector located at 
C$0224, $02253. 



VVBLK I 

Thts Is the Vertical Blank Immediate NMI Interrupt vector located at 
C$0222, $02231. 



VVTP 
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In BASIC, this Is the pointer ([86,873 decimal) to the Variable Value 
Tab I e . 



WARMSTART 

Another name for SYSTEM RESET which Is similar (In the vector 
Initializing functions) to, but not Identical to, a coldstart. 



WIDE PL A YF I ELD 

A screen display width option equal to a width of 192 color clocks. 



WORKMASTER 

In the mass production of cassette tapes, this Is the final master tape 
from which numerous cassette tapes will actually be manufactured. 



WSYNC 

Wait for Horizontal Sync of the electron beam which Is drawing the 
screen Image. The WSYNC register, when written to In any way, pulls down the 
RDY line on the 6502 microprocessor, freezing the 6502 until the electron 
beam drawing the screen image returns to the left edge of the screen. 



ZERO-PAGE 

In the ATARI Personal Computer System, this is the stretch of memory 
which spans locations $0000 to $00FF. 



ZIOCB 

Zero-page I/O Control Block — used to communicate I/O control data 
between CIO and the device handlers. 
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